Skip to main content

Guest

Retrieve a list of guests

Eventmaker provides a paginated API to retrieve the list of guests for your event.

Start with page=1 and paginate every 500 guests.

If you need to know the total number of registered guests for your event, call:

GET /api/v1/events/{id}.format

and check the guest_count property.

The following optional query parameters are available:

  • ?uid=%s — Search for a guest by their unique identifier. Returns an array containing either 0 or 1 guest.

  • ?search=%s — Perform a full-text search across the guest list.

  • ?category[]=%s&category[]=%s — Filter guests by one or more guest category IDs.

These filters can be combined.

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>
 </guests>

Continue incrementing the page query parameter until an empty array is returned.

Create a guest

You can add a new guest to your 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 assign your own guest IDs.
 "uid": "{your_custom_id}",

 // Message displayed on the iOS device when the guest is checked in.
 "message": "Vegan lunch",

 // Additional guest information.
 "guest_metadata": [ { "name": "Has a dog", "value": "Yes" },
 { "name": "Birth year",
 "value": "1960" } 
],

 // Access privileges for specific access 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 assign your own guest IDs. -->
   <uid>9vts5v3nqs</uid>

    <!-- Message displayed on the iOS device when the guest is checked in. -->
   <message>Vegan lunch</message>

    <!-- Additional guest information. -->
   <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>
 
   <!-- Access privileges for specific access 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 a specific guest

Using a guest ID, you can retrieve detailed information about that guest.

The following optional query parameters are available:

  • guest_metadata=true — Includes the guest_metadata array in the response.

  • qrcode_url=true — Includes the qrcode_url property in the response.

  • badges=true — Includes the guest's badges.

  • files=true — Includes the guest's 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&badges=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
GET /api/v1/events/{event_id}/guests/{id}.xml?auth_token=YOUR_API_TOKEN&badges=true
GET /api/v1/events/{event_id}/guests/{id}.xml?auth_token=YOUR_API_TOKEN&files=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, update, or remove guest information.

When updating a field, the new value replaces the existing one. Values are not merged.

For example, if you include a guest_metadata array in your request, it replaces the existing guest_metadata array rather than appending to it.
​

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 (see the POST request for the 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 (see the POST request for the complete list of fields) -->
 </guest>

Response

<!-- 204 No Content -->

Delete a guest

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 -->
Related Articles
Did this answer your question?