Convention

Conventions are accessed via /api/convention.

Properties

See "Object Properties" in Introduction for basic shared properties.

Complete details in ConventionProperties. It also has these extra read-only properties:

has_ended

Indicates whether the convention has ended.

is_scheduling_enabled

Indicates whether the convention has enabled scheduling.

Note that several long-text fields were recently (late 2019) relocated from the Conventions table to separate tables. This includes most text and blob fields. Typically such fields are used to store HTML or JSON data, respectively. See below under "Includes" and "Relationships" for more information.

Related Objects

See "Related Objects" in Introduction for how to use them.

badgeheaderimage

A ConventionImage that will be used to generate printed Badges.

geolocation

A GeoLocation of the general area where the convention will be held.

group

A Group that is in charge of the convention.

headerimage

A ConventionImage that will be displayed at the top of all the convention's pages.

library

A Library that will be available at the convention, if any.

venue

A Venue where the convention will be held.

venuemapimage

A ConventionImage that shows the map of the convention Venue.

Relationships

See "Relationships" in Introduction for how to use them.

badges

Badges created for this convention.

Queryable
firstname
lastname
badge_number
Qualifiers
badge_number
badgetype_id
booth_id
checked_in
conventionreceipt_id
print_count
user_id
verified

badgetypecategories

BadgeTypeCategorys created for this convention.

badgetypes

BadgeTypes created for this convention.

boothoptions

BoothOptions created for this convention.

booths

Booths created for this convention.

Queryable
name
Qualfiers
exhibitor_id
roomzone_id
verified

boothtypes

BoothTypes creeated for this convention.

carts

ConventionCarts created for this convention.

cashdrawers

CashDrawers created for this convention.

conventionjsons

ConventionJson data for this convention. These are stored separately from the convention record because they can contain a lot data that is needed only in specific circumstances. (You can also access these convention child objects under external_jsons.) These fields include:

event_age_groups
event_durations
metatags
exhibitor_custom_fields
volunteer_custom_fields
Queryable
name

You can _include these fields. See the "Includes" section.

conventionwebfiltereds

ConventionWebFiltered data for this convention. These are stored separately from the convention record because they can contain a lot data that is needed only in specific circumstances. (You can also access these convention child objects under external_webfiltereds.) These fields include:

description
exhibitor_application_header
exhibitor_info_email
venue_notes
volunteer_scheduled_greeting
Queryable
name

You can _include these fields. See the "Includes" section.

dayparts

DayParts created for this convention.

Qualifiers
conventionday_id
start_date

days

ConventionDays created for this convention.

Queryable
name
Qualifiers
day_type
use_exhibitor_dates

discounts

Discounts created for this convention.

Queryable
code
name
Qualifiers
enabled
public
use_with_booths
use_with_boothoptions

eventgroups

EventGroups created for this convention.

Queryable
name
Qualifiers
limit_by_badge_type

events

Events created for this convention.

Queryable
event_number
name
Qualifiers
event_number
is_cancelled
is_scheduled
priority
room_id
sold_count
startdaypart_id
type_id

eventsubmissions

EventSubmissions created for this convention.

Queryable
name
user.real_name

The real_name of the event submitter.

Qualifiers
status
type_id

eventtyperooms

EventTypeRooms created for this convention.

Qualifiers
eventtype_id
room_id

eventtypes

EventTypes created for this convention.

Qualifiers
user_submittable

eventwaits

EventWaits created for this convention.

exhibitors

Exhibitors created for this convention.

Queryable
name
Qualifiers
status
user_id

images

ConventionImages created for this convention.

ledgerentries

LedgerEntrys created for this convention.

librarygamecheckouts

The LibraryGameCheckouts associated with this convention.

pages

Pages created for this convention.

playtowins

The PlayToWins associated with this convention.

privileges

ConventionPrivileges created for this convention.

products

Products created for this convention.

Queryable
name
Qualifiers
available_variant_quantity

productvariants

ProductVariants created for this convention.

Queryable
name
Qualifiers
product_id

prototypes

Prototypes created for this convention.

Queryable
description
name
synopsis
Qualifiers
audience
max_players
min_players
status
user_id

receipts

ConventionReceipts created for this convention.

rooms

Rooms created for this convention.

Queryable
name
Qualifiers
booths_available_count
booths_sold_count

roomzones

RoomZones created for this convention.

shifts

Shifts created for this convention.

Queryable
name
Qualifiers
conventionday_id
shifttype_id
shifttype.room_id

The room_id field in the Shift's related ShiftType. You must include parameter _include_related_objects=shifttype with the request for this to work.

shifttypes

ShiftTypes created for this convention.

Qualifiers
room_id

slots

Slots created for this convention.

Queryable
name
Qualifiers
conventionday_id
daypart_id
event_id
room_id
space_id

soldproducts

SoldProducts created for this convention.

Queryable
productvariant.name
Qualifiers
badge_id
picked_up
productvariant_id
verified

spaces

Spaces created for this convention.

Queryable
name
Qualifiers
room_id

sponsorships

The Sponsorships available to Exhibitors for the convention.

Queryable
name
Qualifiers
sellable

sponsors

The exhibitor Sponsors for the convention.

Qualifiers
exhibitor_id
sponsorship_id
verified

supplyorders

The SupplyOrders for the convention.

Queryable
supplyorder_number
ship_to_name
ship_to_companyname
ship_to_street1
ship_to_street2
ship_to_city
ship_to_state
ship_to_zipcode
contact_email
contact_phone

tickets

Tickets created for this convention.

Queryable
event.name

The name of the Event the Ticket is for.

ticket_number
Qualifiers
badge_id
event_id
picked_up
verified

updates

News Updates created for this convention.

volunteers

Volunteers for this convention.

Queryable
email_address
firstname
lastname
phone_number

volunteershifts

VolunteerShifts created for this convention.

Queryable
volunteer.firstname

The firstname field in the VolunteerShift's related Volunteer record. You must include parameter _include_related_objects=volunteer with the request for this to work.

volunteer.lastname

The lastname field in the VolunteerShift's related Volunteer record. You must include parameter _include_related_objects=volunteer with the request for this to work.

Qualifiers
shift_id
shift.conventionday_id

The conventionday_id field in the VolunteerShift's related Shift record. You must include parameter _include_related_objects=shift with the request for this to work.

status
volunteer_id
volunteer.user_id

The user_id field in the VolunteerShift's related Volunteer record. You must include parameter _include_related_objects=volunteer with the request for this to work.

Includes

See "Includes" in Introduction for how to use them.

payout_ready

Indicates that the convention's group's leader has set up the convention to receive payouts. Convention sales cannot occur if payout is not set up or if it changes to a state where it is not set up (e.g., if the convention group leader were to change to one without their payout setup completed).

ConventionJson fields

See ConventionJson for the list of specific JSON "fields" you can include.

ConventionWebfiltered fields

See ConventionWebfiltered for the list of specific webfiltered (HTML) "fields" you can include.

Services

The services used to fetch and manipulate conventions.

Search Conventions

Returns conventions that have not yet ended. By default it only returns public conventions, but if you provide a session_id it will also include any conventions run by Groups you are a Member of.

 GET /api/convention
Optional Params
query

A partial convention name.

Returns:

 {
    "items" : [
        {
            "id" : "xxx",
            "name" : "Big Apple Con 2017",
            ...
        },
        ...
    ],
    "paging" : {...}
 }

Create Convention

 POST /api/convention
Required Params
session_id
name
group_id
geolocation_id

Returns the same as a normal read.

Read Convention

 GET /api/convention/xxx

Returns:

 {
   "id" : "xxx",
   "name" : "Big Apple Con 2017",
   ...
 }

Update Convention

 PUT /api/convention/xxx

Returns the same as a normal read.

Delete Convention

 DELETE /api/convention/xxx

Returns:

 {
   "success" : 1
 }

Search Users

There are lots of functions where you'll need to assign a User id, so you'll need to be able to look up users. However, since you are not a site administrator you don't have the rights to look up users through the normal API. This API gives you a limited view of users that includes some data the normal User API wouldn't if you are a convention runner. It requires you to be logged in.

 GET /api/convention/xxx/user
Optional Params
badge_number

Look up a user by a specific badge nubmer in your convention.

badge_name

Look up users by a partial badge name in your convention.

query

Generically search users based upon partial usernames, real names, or email addresses.

Returns:

 {
    "paging" : {...},
    "items" : [
        {
          "id" : "xxx",
          "real_name" : "Joe User",
          ...
        },
        ...
    ]
 }

Search Financials

Like ledgerentries but with special searching capabilities.

 GET /api/convention/xxx/financials
Optional Params
badge_name

Use this field to do a partial search on badge name.

order_number

Limit ledger entries to a specific order number.

category

Limit ledger entries to a specific category.

Collect Ticket

Marks a Ticket collected. Will reject generic tickets.

 POST /api/convention/xxx/collect-ticket
Required Params
ticket_number

Returns the same as a Ticket read.

Collect Generic Ticket

Marks a generic Ticket collected. Will reject a normal ticket.

 POST /api/convention/xxx/collect-ticket
Required Params
ticket_number
event_id

Returns the same as a Ticket read.

Badge Summary

Summarizes the state of all your badges.

 GET /api/convention/xxx/badge-summary

Returns

 {
     "checked_in" : 43,
     "printed" : 172,
     "sold" : 531,
     "in_carts" : 4,
     "verified" : 546,
 }

verified are all badges that are valid. Therefore, if you subtract sold from verified you'd know how many badges are administratively created.

Badge Sales History

Summarizes when badges were purchased.

 GET /api/convention/xxx/badge-sales-history

Returns:

 {
     "sales" : [
        {
            "month" : "2017-01",
            "total_sales" : 13,
        },
        ...
     ]
 }

Hosts

A list of Users that run convention Events. Th

 GET /api/convention/xxx/hosts
Queryable
name

Returns:

 {
    "paging" : {...},
    "items" : [
        {
          "firstname": "Host",
          "lastname": "McHoster",
          ...
        },
        ...
    ]
 }

Days With Shifts For Volunteers

The list of ConventionDays that have associated Shifts.

 GET /api/convention/xxx/days/with-shifts

Rooms With Shifts For Volunteers

The list of Rooms that have associated Shifts.

 GET /api/convention/xxx/rooms/with-shifts

Message Volunteers

Creates a Wingman job to send a message to convention Volunteers.

 POST /api/convention/xxx/message-volunteers
Required Params
body

The message body.

reply_to

The message reply-to address.

subject

The message subject.

Returns:

 { "success": 1 }

Volunteers By Status

The list of Convention Volunteers by their VolunteerShift status. Note that the different endpoints can return the same volunteer(s). If a volunteer has a scheduled shift, and an unscheduled shift, that volunteer will be included in both the scheduled and unscheduled lists.

 GET /api/convention/xxx/volunteers/scheduled
 GET /api/convention/xxx/volunteers/unscheduled
 GET /api/convention/xxx/volunteers/declined
Optional Params
shift_id

Limit volunteers to those associated with a specific Shift.

query

Use this field to do a partial search on volunteer name.

Returns:

 {
    "paging" : {...},
    "items" : [
        {
          "id" : "xxx",
          "firstname": "Joe",
          "lastname": "Volunteer",
          ...
        },
        ...
    ]
 }

Count of Volunteers By Status

The count of Convention Volunteers by their VolunteerShift status. Note that the different endpoints can count the same volunteer(s). If a volunteer has a scheduled shift, and an unscheduled shift, that volunteer will be included in the counts of both the scheduled and unscheduled volunteers.

 GET /api/convention/xxx/volunteers/scheduled/count
 GET /api/convention/xxx/volunteers/unscheduled/count
 GET /api/convention/xxx/volunteers/declined/count
Optional Params
shift_id

Limit count of volunteers to those associated with a specific Shift.

Returns:

 {
    "scheduled_volunteers_count" : 5
 }

Or unscheduled_volunteers_count, or declined_volunteers_count.

Shifts Available to Volunteers

The list of Shifts that still need Volunteers.

 GET /api/convention/xxx/shifts/available
Optional Params
conventionday_id

Limit shifts to those for a specific ConventionDay.

room_id

Limit shifts to those for a specific Room.

Returns:

 {
    "paging" : {...},
    "items" : [
        {
          "id" : "xxx",
          "name" : "Sunday Morning Shift",
          ...
        },
        ...
    ]
 }

Days For Events

The list of ConventionDays that are of type Event.

 GET /api/convention/xxx/event-days

Returns:

 {
    "paging" : {...},
    "items" : [
        {
          "id" : "xxx",
          "name" : "Day 1",
          "day_type" : "events",
          ...
        },
        ...
    ]
 }