Retrieve the list of guests

Eventmaker provides a paginaged API to retrieve the list of guests of your event. Starts at page=1. Paginate every 500 guests. If you want to know how many guests registered to your event, you should query GET /api/v1/events/{id}.format and look at the property guest_count.

Optional query parameters are:

  1. ?uid=%s: Search a guest by his/her uid. Will return an array of 0 or 1 guest.
  2. ?search=%s: Full-text search in the guest list.
  3. ?category[]=%s&category[]=%s: Filter by the given guest category ids.
  4. ?since=date or /and ?before=date: Date range on the guest creation date
  5. ?updated_since=date or/and ?updated_before=date: similar to since or update, but search trough guest updating date

You can compound these filter parameters

JSON

Request

GET /api/v1/events/{event_id}/guests.json?page=1&auth_token=YOUR_API_TOKEN

Response

// 200 OK
[
  {
    // the first guest
  },
  {
    // the second guest
  }
]

XML

Request

GET /api/v1/events/{event_id}/guests.xml?page=1&auth_token=YOUR_API_TOKEN

Response

<!-- 200 OK -->
<?xml version="1.0" encoding="UTF-8"?>
<guests type="array">
  <guest>
    <!-- [...] -->
  </guest>
  <guest>
    <!-- [...] -->
  </guest>
</guest>

You can increment the page query string parameter until you get an empty array.

Create a new guest

You can add a new person to your event guest list.

JSON

Request

POST /api/v1/events/{event_id}/guests.json?auth_token=YOUR_API_TOKEN
Content-Type: application/json; charset=utf-8
{
  "guest_category_id": "{guest_category_id}",
  "email":             "john.smith@acme.org",
  "first_name":        "John",
  "last_name":         "Smith",
  "company_name":      "Acme Inc.",
  "position":          "CEO",
  "phone_number":      "001122334455",

  // Use this field if you want to choose your owns ids for your guests.
  "uid": {your_custom_id},

  // Use this field if you want a message that appear on the iOS device when the guest is checked-in.
  "message": "Vegan lunch",

  // You can pass any other information abotu the guest in this array.
  "guest_metadata": [
    { "name": "Has a dog",  "value": "Yes" },
    { "name": "Birth year", "value": "1960" }
  ]

  // You can pass an array of access privileges for specific check-in points
  "access_privileges_attributes": [
    { "access_once": true,  "accesspoint_id": "{workshop_foo_id}" },
    { "access_once": false, "accesspoint_id": "{vip_room_id}" },
  ]
}

Response

// 201 Created
{
   "badge_completed": false,
   "rsvp_status": "not_replied",
   "_id": "50af6426bbfa805f760005ac",
   "guest_category_id": "{guest_category_id}",
   "email": "john.smith@acme.org",
   "first_name": "John",
   "last_name": "Smith",
   "company_name": "Acme Inc.",
   "position": "CEO",
   "phone_number": "001122334455",
   "message": "Vegan lunch",
   "event_id": "{event_id}",
   "uid": "9vts5v3nqs",
   "updated_at": "2012-11-23T11:55:18Z",
   "created_at": "2012-11-23T11:55:18Z",
   "badge_url": null,
   "qrcode_url": null,
   "guest_metadata":
   [
      { "name": "Has a dog",  "value": "Yes" },
      { "name": "Birth year", "value": "1960" }
   ],
   "access_privileges":
   [
     // Array of all access privileges
   ]
}

XML

Request

POST /api/v1/events/{event_id}/guests.xml?auth_token=YOUR_API_TOKEN
Content-Type: application/xml; charset=utf-8
<guest>
  <guest-category-id>{guest_category_id}</guest-category-id>
  <email>john.smith@acme.org</email>
  <first-name>John</first-name>
  <last-name>Smith</last-name>
  <company-name>Acme Inc.</company-name>
  <position>CEO</position>
  <phone-number>001122334455</phone-number>

  <!-- Use this field if you want to choose your owns ids for your guests. -->
  <uid>9vts5v3nqs</uid>

  <!-- Use this field if you want a message that appear on the iOS device when the guest is checked-in. -->
  <message>Vegan lunch</message>

  <!-- You can pass any other information abotu the guest in this hash. -->
  <guest-metadata type="array">
    <guest-metadatum>
      <name>Has a dog</name>
      <value>Yes</value>
    </guest-metadatum>
    <guest-metadatum>
      <name>Birth year</name>
      <value>1960</value>
    </guest-metadatum>
  </guest-metadata>

  <!-- You can pass an array of access privileges if the guest can access specific check-in points -->
  <access-privileges-attributes type="array">
    <access-privilege>
      <access-once type="boolean">true</access-once>
      <accesspoint-id>{workshop_foo_id}</accesspoint-id>
    </access-privilege>
    <access-privilege>
      <access-once type="boolean">false</access-once>
      <accesspoint-id>{vip_room_id}</accesspoint-id>
    </access-privilege>
  </access-privileges-attributes>
</guest>

Response

<!-- 201 Created -->
<?xml version="1.0" encoding="UTF-8"?>
<guest>
  <_id>50af6426bbfa805f760005ac</_id>
  <badge-completed type="boolean">false</badge-completed>
  <badge-url></badge-url>
  <company-name>Acme Inc.</company-name>
  <email>john.smith@acme.org</email>
  <event-id>{event_id}</event-id>
  <first-name>John</first-name>
  <guest-category-id>{guest_category_id}</guest-category-id>
  <last-name>Smith</last-name>
  <message>Vegan lunch</message>
  <phone-number>001122334455</phone-number>
  <position>CEO</position>
  <rsvp-status>not_replied</rsvp-status>
  <uid>9vts5v3nqs</uid>
  <created-at type="datetime">2012-11-23T11:55:18Z</created-at>
  <updated-at type="datetime">2012-11-23T11:55:18Z</updated-at>
  <access-privileges type="array">
    <access-privilege>
      <!-- [...] -->
    <access-privilege>
    </access-privilege>
      <!-- [...] -->
    </access-privilege>
  </access-privileges>
  <guest-metadata type="array">
    <guest-metadatum>
      <name>Has a dog</name>
      <value>Yes</value>
    </guest-metadatum>
    <guest-metadatum>
      <name>Birth year</name>
      <value>1960</value>
    </guest-metadatum>
  </guest-metadata>
</guest>

Retrieve information about a guest

With the id of a guest, you can details about him. We provide 2 optional parameters to pass as query string parameters:

  • guest_metadata=true will put the guest_metadata array in the object returned
  • qrcode_url=true will put the qrcode_url string in the object returned
  • badges=true will provide an array of the guest badges
  • files=true will provide an array of attached files

JSON

Request

GET /api/v1/events/{event_id}/guests/{id}.json?auth_token=YOUR_API_TOKEN
GET /api/v1/events/{event_id}/guests/{id}.json?auth_token=YOUR_API_TOKEN&qrcode_url=true
GET /api/v1/events/{event_id}/guests/{id}.json?auth_token=YOUR_API_TOKEN&guest_metadata=true
GET /api/v1/events/{event_id}/guests/{id}.json?auth_token=YOUR_API_TOKEN&files=true

Response

// 200 OK
{
   "_id": "{id}",
   "guest_category_id": "{guest_category_id}",
   "first_name": "John",
   "last_name": "Smith",
   // [...]
}

XML

Request

GET /api/v1/events/{event_id}/guests/{id}.xml?auth_token=YOUR_API_TOKEN
GET /api/v1/events/{event_id}/guests/{id}.xml?auth_token=YOUR_API_TOKEN&qrcode_url=true
GET /api/v1/events/{event_id}/guests/{id}.xml?auth_token=YOUR_API_TOKEN&guest_metadata=true

Response

<!-- 200 OK -->
<?xml version="1.0" encoding="UTF-8"?>
<guest>
  <_id>{id}</_id>
  <guest-category-id>{guest_category_id}</guest-category-id>
  <first-name>John</first-name>
  <last-name>Smith</last-name>
  <!-- [...] -->
</guest>

Update a guest

You can add complementary information, update or delete your guests fields. Be careful that these modifications are done in place, not concatenated to existing fields. For instance, if you provide a guest_metadata array in your request, they won’t be appended to existing entries in the guest, but will replace them.

JSON

Request

PUT /api/v1/events/{event_id}/guests/{id}.json?auth_token=YOUR_API_TOKEN
Content-Type: application/json; charset=utf-8
{
  // Fields to update (View the POST request for a complete list of fields)
}

Response

// 204 No Content

XML

Request

PUT /api/v1/events/{event_id}/guests/{id}.xml?auth_token=YOUR_API_TOKEN
Content-Type: application/xml; charset=utf-8
<guest>
  <!-- Fields to update (View the POST request for a complete list of fields) -->
</guest>

Response

<!-- 204 No Content -->

Delete a guest

You can delete guests (which is irreversible).

JSON

Request

DELETE /api/v1/events/{event_id}/guests/{id}.json?auth_token=YOUR_API_TOKEN

Response

// 204 No Content

XML

Request

DELETE /api/v1/events/{event_id}/guests/{id}.xml?auth_token=YOUR_API_TOKEN

Response

<!-- 204 No Content -->