NAV
code

Introduction

The Attendease API is organized around REST. Our API is designed to have predictable, resource-oriented URLs and to use HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which can be understood by off-the-shelf HTTP client. JSON will be returned in all responses from the API, including errors.

Event API

The Event API provides various means of reading and writing to your event.

API Endpoint

Your API Endpoint uses your event’s subdomain.

e.g. https://foo.attendease.com/

Authentication

As an Attendee

Example request

curl -i "https://foo.attendease.com/api/sessions.json?email=foo@bar.com&password=foobar"
curl -i "https://foo.attendease.com/api/sessions.json?attendee_token=my-attendee-token"
$ curl -H "X-Attendee-Token: my-attendee-token" -i
"https://foo.attendease.com/api/sessions.json"

Example response

A successful authentication result in the following:

HTTP Status: 404

"..."

Any authentication error will result in the following:

HTTP Status: 401

{
  "error":"Could not authenticate you."
}

Many API calls require authentication. Authentication to the API occurs either via query params, HTTP Basic Auth or an Access Token.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. You must authenticate for all requests.

As a query string parameter

?email=foo@bar.com&password=foobar

or

?attendee_token=my-attendee-token

As an HTTP header

X-Attendee-Token: my-attendee-token

Parameters

Key Description
email The attendee’s email address. This will be the username for basic auth.
password The attendee’s password.
attendee_token Your attendee access token to authenticate without email/password.

As an Event Manager

Example request

curl -i "https://foo.attendease.com/api/sessions.json?event_token=my-event-token"
$ curl -H "X-Event-Token: my-event-token" -i
"https://foo.attendease.com/api/sessions.json"

Example response

A successful authentication result in the following:

HTTP Status: 404

"..."

Any authentication error will result in the following:

HTTP Status: 401

{
  "error":"Could not authenticate you."
}

You can use your event token as either an event_token parameter, or via the X-Event-Token header.

As a query string parameter

?event_token=my-event-token

Failed attempts will result in a 403 HTTP status.

As an HTTP header

X-Event-Token: my-event-token

Parameters

Key Description
event_token Your event access token.

mailto:support@attendease.com?subject=I’d like to make my event private

Authorization

Example request

curl "https://foo.attendease.com/api/sessions/unpublished.json?attendee_token=my-attendee-token"

Example response

A successful authentication result in the following:

HTTP Status: 404

"..."

Any authorization error will result in the following:

HTTP Status: 403

{
  "error":"You do not have the correct permissions to access this."
}

Each API call will define which authentication is needed.

Key Description
Publicly accessible No authentication needed unless the event is set private. In this case, authentication as either an attendee or an event manager is required
Attendee accessible Requires authentication as an Attendee
Event Manager accessible Requires authentication as an Event Manager

Failed attempts will result in a 403 HTTP status.

Metadata

Example request

curl "https://foo.attendease.com/api/rooms.json?meta=true"

Example response

[
   {
      "id":"5164751fecdcc4d8a9000014",
      "name":"150AB",
      "capacity":80,
      "meta":{
         "coords":"40,215",
         "level":"LACC Level 1",
         "custom": "data"
      }
   },
   {
      "id":"5164751fecdcc4d8a9000015",
      "name":"153AB",
      "capacity":80,
      "meta":{
         "coords":"89,214",
         "level":"LACC Level 1"
      }
   },
   {
      "id":"5164751fecdcc4d8a9000016",
      "name":"MTT 515A",
      "capacity":800,
      "meta":{
         "coords":"448,51",
         "level":"LACC Level 2"
      }
   },
]

Requesting metadata from resources

Many API calls can return additional metadata.

Sometimes we need a bit more information to make our lives as developers easier, we can access metadata on several resources if we need to.

Parameters

Key Description
meta This is a boolean string of true or 1. If the metadata fields exist for the resource they will be returned with the request.

For example if we wanted additional data that was saved in our rooms resource like coords and level we could request the rooms like this:

Event

The bread and butter of the Attendease event management system. Without an event there can be no attendees.

Get event properties

Example request

curl "https://foo.attendease.com/api/properties.json"

Example response

{
  "id":"your-event-subdomain",
  "locale":"en",
  "type":"event",
  "name":"My Amazing Event",
  "dates":[
    {
      "id":"51955dd4ecdcc493a9000006",
      "date":"2013-10-24",
      "start_time":"06:00",
      "end_time":"23:59",
      "date_formatted":"October 24, 2013",
      "start_time_formatted":"6:00 AM",
      "end_time_formatted":"11:59 PM"
    },
    {
      "id":"51955dd4ecdcc493a9000007",
      "date":"2013-10-25",
      "start_time":"06:00",
      "end_time":"23:59",
      "date_formatted":"October 25, 2013",
      "start_time_formatted":"6:00 AM",
      "end_time_formatted":"11:59 PM"
    }
  ],
  "minute_increments":15,
  "primary_filter_id":null
}

This gets the basic information about the event including the days, times and some other properties.

HTTP Request

GET /api/properties.json

Details

Publicly accessible

Get deleted resources

Example request

curl "https://foo.attendease.com/api/deletions.json"

Example response

{
  "session_ids":["51f83534ecdcc437f2000001"],
  "room_ids":[],
  "presenter_ids":["51dacfcdecdcc446e5000005","51f6f9f0ecdcc4bd99000001"],
  "filter_ids":["51e42fe7ecdcc4d44f000002","51e42ff8ecdcc4d44f000003"],
  "sponsor_ids":[]
}

Getting a list of any event resources that have been deleted by the administrator is useful when syncing data from the Attendease API.

HTTP Request

GET /api/deletions.json

Details

Attendee accessible

Parameters

Optional

Key Description
since A unix timestamp which will only return attendees who have registered after this date. ?since=1376589058598

Attendees

The people attending your event.

Logging in as an attendee

Example request

curl "https://foo.attendease.com/api/authenticate.json"

Example response

{
  "id":"525594a74aba5a3b6c000019",
  "name":"Leatha Jacobson",
  "first_name":"Leatha",
  "last_name":"Jacobson",
  "email":"attendee@example.org",
  "access_token":"db655179-234d-4f24-a900-4de677442235",
  "pass_quantity":1,
  "pass_name":"sectarian",
  "registration_code":"",
  "price":4200,
  "amount_paid":0,
  "amount_owing":0,
  "checked_in_at":"",
  "profile_url":"https://bit.ly/1g05qW7",
  "registered_at":"2013-10-09T10:38:47-07:00",
  "pass":{
    "id":"525594a74aba5a3b6c000016",
    "name":"sectarian",
    "description":"",
    "days_in_effect":[
      "2013-10-23",
      "2013-10-23"
    ]
  },
  "instances":[
    {
      "id":"525594a74aba5a3b6c00001f",
      "code":"ABC123-1",
      "room_id":"525594a74aba5a3b6c00001e",
      "duration":60,
      "date":"2013-10-23",
      "time":"16:20",
      "date_formatted":"October 23, 2013",
      "time_formatted":"4:20 PM",
      "session_id":"525594a74aba5a3b6c00001d"
    }
  ]
}

If you are building a front end to the event, you may want your attendees to sign in at some point.

HTTP Request

POST /api/authenticate.json

Details

Attendee accessible

Logging out as an attendee

Example request

curl "https://foo.attendease.com/api/logout.json"

Example response

{
  "status": "Signed out successfully."
}

Our API Endpoint supports sessions and if you make use of these sessions you can log out.

HTTP Request

GET /api/logout.json

Resetting an attendee’s password

Example request

curl "https://foo.attendease.com/api/forgot_password.json?email=foo@bar.com"

Example response (success)

{
  "success": true,
  "status": "An email has been sent with password reset instructions."
}

Example response (error)

{
  "success": false,
  "status": "No user found with email address."
}

If you know the attendee’s email address, you can trigger an email to allow them to reset their password if they have forgotten it.

HTTP Request

GET /api/forgot_password.json

or

POST /api/forgot_password.json

Parameters

Key Description
email The attendee email address

Getting a list of attendees

Example request

curl "https://foo.attendease.com/api/attendees.json"

Example response

[
  "..."
]

Download a list of all the attendees attending your event.

HTTP Request

GET /api/attendees.json

Details

Event Manager accessible Supports metadata

Parameters

Optional

Key Description
since A unix timestamp which will only return attendees who have registered after this date. ?since=1376589058598

Sessions

People go to events for many reasons… event sessions are one of those reasons.

Get list of all published sessions

Example request

curl "https://foo.attendease.com/api/sessions.json"

Example response

[
  {
    "id":"51a8f505f13ee0ce44000035",
    "name":"General Session: Keynote",
    "code":"ABC123",
    "description":"General Keynote Session - Lorem ipsum dolor sit amet, consectetuer adipiscing elit.",
    "filters":[],
    "locked":false,
    "speaker_ids":[],
    "featured":true,
    "instances":[
      {
        "id":"51a8faf3f13ee0672c000003",
        "code":"ABC123-1",
        "room_id":"51a8f676f13ee0ce44000039",
        "duration":60,
        "date":"2013-10-24",
        "time":"09:00",
        "date_formatted":"October 24, 2013",
        "time_formatted":"9:00 AM",
        "capacity":60,
        "attendance":2
      }
    ],
    "attachments":[
      {
        "id":"5488bf9b0482930776000001",
        "name":"Attendease",
        "url":
        "https://attendease.com"
      }
    ]
  },
  {
    "id":"51a8f7bdf13ee01a33000003",
    "name":"1001 Uses For Lipstick",
    "code":"ABC456",
    "description":"Nam cursus. Morbi ut mi. Nullam enim leo, egestas id, condimentum at, laoreet mattis, massa.",
    "filters":[
      "51c21ea0f13ee041b500000a",
      "51a8fa07f13ee01a33000007",
      "51a8fa07f13ee01a33000006",
      "51a8f71bf13ee0fc40000001"
    ],
    "locked":false,
    "speaker_ids":[
      "51a8f694f13ee0ce4400003c"
    ],
    "featured":false,
    "instances":[
      {
        "id":"51a8f7eef13ee01a33000004",
        "code":"ABC456-1",
        "room_id":"51a8f64bf13ee0ce44000038",
        "duration":60,
        "date":"2013-10-24",
        "time":"10:00",
        "date_formatted":"October 24, 2013",
        "time_formatted":"10:00 AM",
        "capacity":40,
        "attendance":11
      },
      {
        "id":"51a9242ff13ee0e70a000002",
        "code":"ABC456-2",
        "room_id":"51a8f689f13ee0ce4400003b",
        "duration":60,
        "date":"2013-10-25",
        "time":"09:00",
        "date_formatted":"October 25, 2013",
        "time_formatted":"9:00 AM",
        "capacity":40,
        "attendance":26
      }
    ],
    "attachments":[]
  },
  ...
]

These are all the available published sessions and instances for the event.

HTTP Request

GET /api/sessions.json

Details

Publicly accessible Supports metadata

Get list of all published and unpublished sessions

Example request

curl "https://foo.attendease.com/api/sessions/all.json"

Example response

[
  {
    ...
    "published": true,
    "notes": [
      {
        "id": "53ffc23f6828d98e4b000002",
        "user_id": "53ffc2876828d98e4b000007",
        "created_at": "2014-08-26T15:38:03Z",
        "body": "A session note."
      },
    ],
    "instances":[
      {
        "id":"51a8f7eef13ee01a33000004",
        "code":"ABC456-1",
        "room_id":"51a8f64bf13ee0ce44000038",
        "duration":60,
        "date":"2013-10-24",
        "time":"10:00",
        "date_formatted":"October 24, 2013",
        "time_formatted":"10:00 AM",
        "capacity":40,
        "attendance":0,
        "attendee_ids":[
        ]
      },
      {
        "id":"51a9242ff13ee0e70a000002",
        "code":"ABC456-2",
        "room_id":"51a8f689f13ee0ce4400003b",
        "duration":60,
        "date":"2013-10-25",
        "time":"09:00",
        "date_formatted":"October 25, 2013",
        "time_formatted":"9:00 AM",
        "capacity":40,
        "attendance":3,
        "attendee_ids":[
          "1234567890abcdef1",
          "1234567890abcdef2",
          "1234567890abcdef3"
        ]
      }
    ],
      ...
    ],
    ...
  },
  {
    ...
    "published": false,
    "notes": [],
    ...
  },
  ...
]

These are all the published and unpublished sessions and instances for the event. This is for event manager use only.

Same structure as the sessions list, but with additional fields published and notes as well as the attendee_ids for scheduled attendees.

HTTP Request

GET /api/sessions/all.json

Details

Event Manager accessible Supports metadata

Get list of all unpublished sessions

Example request

curl "https://foo.attendease.com/api/sessions/unpublished.json"

Example response

[
  {
    ...
    "published": false,
    "notes": [
      {
        "id": "53ffc4646828d98e4b000014",
        "user_id": "53ffc4756828d98e4b00001b",
        "created_at": "2014-08-27T23:58:50Z",
        "body": "A session note."
      },
      ...
    ],
    "instances":[
      {
        "id":"51a8f7eef13ee01a33000004",
        "code":"ABC456-1",
        "room_id":"51a8f64bf13ee0ce44000038",
        "duration":60,
        "date":"2013-10-24",
        "time":"10:00",
        "date_formatted":"October 24, 2013",
        "time_formatted":"10:00 AM",
        "capacity":40,
        "attendance":0,
        "attendee_ids":[
        ]
      },
      {
        "id":"51a9242ff13ee0e70a000002",
        "code":"ABC456-2",
        "room_id":"51a8f689f13ee0ce4400003b",
        "duration":60,
        "date":"2013-10-25",
        "time":"09:00",
        "date_formatted":"October 25, 2013",
        "time_formatted":"9:00 AM",
        "capacity":40,
        "attendance":3,
        "attendee_ids":[
          "1234567890abcdef1",
          "1234567890abcdef2",
          "1234567890abcdef3"
        ],
      }
    ],
    ...
  },
  {
    ...
    "published": false,
    "notes": [],
    ...
  },
  ...
]

These are all the unpublished sessions and instances for the event. This is for Event Manager use only.

Same structure as the sessions list, but with additional fields published and notes as well as the attendee_ids for scheduled attendees.

HTTP Request

GET /api/sessions/unpublished.json

Details

Event Manager accessible Supports metadata

Session Instances

Sessions usually have a location and time… sessions instances define this. Attendees will confirm their attendance to a session through the session instance.

Get capacities

Example request

curl "https://foo.attendease.com/api/capacities.json"

Example response

[
  {
    "instance_id":"51647527ecdcc4d8a900005c",
    "capacity":50,
    "attendance":22
  },
  {
    "instance_id":"51647527ecdcc4d8a9000064",
    "capacity":50,
    "attendance":17
  },
  {
    "instance_id":"51647527ecdcc4d8a9000078",
    "capacity":80,
    "attendance":56
  },
  {
    "instance_id":"51647527ecdcc4d8a900007e",
    "capacity":80,
    "attendance":37
  },
  ...
]

This allows you to quickly check if sessions are filling up or if some are full.

HTTP Request

GET /api/capacities.json

Details

Publicly accessible

Scheduling a session instance

Example request

curl "https://foo.attendease.com/api/capacities.json"

Example response

{
  "success":true,
  "status":"registered",
  "instance":
  {
    "id":"51a8f7eef13ee01a33000004",
    "code":"101-1",
    "room_id":"51a8f64bf13ee0ce44000038",
    "duration":60,
    "date":"2013-10-24",
    "time":"10:00"
  }
}

If the event supports waiting list and we use use_waiting_list

{
  "success":true,
  "status":"on_waiting_list",
  "instance":
  {
    "id":"51a8f7eef13ee01a33000004",
    "code":"101-1",
    "room_id":"51a8f64bf13ee0ce44000038",
    "duration":60,
    "date":"2013-10-24",
    "time":"10:00"
  }
}
{
  "success":false,
  "errors":"Sorry, this session is locked."
}
{
  "success":false,
  "errors":"Sorry, this session is full."
}
{
  "success":false,
  "errors":"Sorry, you do not have permission to schedule this session."
}
{
  "success":false,
  "errors":"This session conflicts with: Another session name at 12:00"
}

An attendee can schedule a session instance if they want to reserve their spot for that day/time/room.

HTTP Request

POST /api/schedule.json

or

POST /api/schedule/:instance_id_or_code.json

Details

Attendee accessible Supports metadata

Parameters

Required

Key Description
instance_id_or_code The ID or code of the session instance. This is required unless it is included in the url as indicated above.

Optional

Key Description
force Value true or false. Force a scheduling conflict resolution. If we schedule an overlapping session automatically take care of unscheduling the conflicting session.
use_waiting_list number of records in this page (<= page_size)

Getting schedule for an attendee

Example request

curl "https://foo.attendease.com/api/schedule_status.json"

Example response

{
  "51a8f7eef13ee01a33000004": "attendease-status-available",
  "51a8f64bf13ee0ce44000038": "attendease-status-scheduled"
}
{
  "120-1": "attendease-status-available",
  "120-2": "attendease-status-scheduled"
}

Retrieve a list of all the instances and their statuses for the authenticated attendee.

HTTP Request

GET /api/schedule_status.json

Details

Attendee accessible

Parameters

Optional

Key Description
use_code Pass true to use the instance code rather than the instance id.

Status description

Status Description
attendease-status-available This instance is scheduable.
attendease-status-scheduled The attendee is scheduled in this instance.
attendease-status-on-waiting-list The attendee is on the waiting list.
attendease-status-has-waiting-list A waiting list is available for this instance.
attendease-status-cannot-schedule The attendee cannot schedule.
attendease-status-conflicts The attendee cannot schedule they are already scheduled for an instance at the same date/time.
attendease-status-full The attendee cannot schedule, the instance is full.
attendease-status-cannot-schedule-invalid-pass The attendee cannot schedule, they have an invalid pass.
attendease-status-cannot-schedule-disallowed-pass The attendee cannot schedule, they have a pass that does not allow scheduling this session.
attendease-status-cannot-schedule-locked The attendee cannot schedule, the instance is locked.
attendease-status-cannot-unschedule-locked The attendee cannot unschedule, the instance is locked.
attendease-status-cannot-schedule-maximum-reached The attendee cannot schedule, the maximum number of scheduled instances has been reached for this session.
attendease-status-read-only The attendee cannot cannot schedule, the event is read only.
attendease-status-not-logged-in When the attendee is not logged in (no authentication is provided).
attendease-status-presenting The attendee cannot schedule since they are presenting the session. This currently requires additional linking logic. Talk to us about this before implementing it.

Presenters

An event is like a meal. A session is like a sandwich. The session instance is like the bread and the speaker is like the filler. Yum.

Get list of all presenters

Example request

curl "https://foo.attendease.com/api/presenters.json"

Example response

[
  {
    "id":"51a8f622f13ee0ce44000036",
    "first_name":"Tim",
    "last_name":"Cook",
    "company":"Apple Inc.",
    "title":"CEO",
    "profile_url":"https://si0.twimg.com/profile_images/3177796455/c7368e2302e1c815c80f8321cd850c1a_bigger.jpeg",
    "bio":"Lemon drops muffin danish tiramisu jelly beans cookie.",
    "featured":true,
    "social":{
      "twitter":"@something",
      "facebook":"something",
      "linkedin":"something"
    }
  },
  {
    "id":"51a8f694f13ee0ce4400003c",
    "first_name":"Barack",
    "last_name":"Obama",
    "company":"United States of America",
    "title":"President",
    "profile_url":"https://si0.twimg.com/profile_images/2981240402/410b6834de7377ceae90dec181fdcd5c_bigger.jpeg",
    "bio":"Dragée gummi bears sugar plum dessert cookie biscuit croissant.",
    "featured":false,
    "social":{
      "twitter":"@something",
      "facebook":"something",
      "linkedin":"something"
    }
  },
  ...
]

These are all the presenters at the event.

HTTP Request

GET /api/presenters.json

Details

Publicly accessible Supports metadata

Get list of all published and unpublished presenters

Example request

curl "https://foo.attendease.com/api/presenters/all.json"

Example response

[
  {
    ...
    published: true
    ...
  },
  {
    ...
    published: false
    ...
  },
  ...
]

These are all the published and unpublished presenters for the event. This is for Event Manager use only.

Same structure as the presenters list except with the additional published keys.

HTTP Request

GET /api/presenters/all.json

Details

Event Manager accessible Supports metadata

Get list of all unpublished presenters

Example request

curl "https://foo.attendease.com/api/presenters/unpublished.json"

Example response

[
  {
    ...
    published: true
    ...
  },
  {
    ...
    published: false
    ...
  },
  ...
]

These are all the unpublished presenters for the event. This is for Event Manager use only.

Same structure as the presenters list except with the additional published keys.

HTTP Request

GET /api/presenters/unpublished.json

Details

Event Manager accessible Supports metadata

Surveys

Surveys for the event.

Get list of all enabled surveys

Example request

curl "https://foo.attendease.com/api/surveys.json"

Example response

[
  {
    "id": "53278a99ecdcc44aad000013",
    "name": "Session Feedback",
    "description": "Please provide your feedback.",
    "type": "session",
    "public": false,
    "slug": null,
    "session_ids": [
      "531f46a2ecdcc43dbe0000ca",
      "531f46a0ecdcc43dbe000088",
      "531f46a6ecdcc43dbe000111"
    ],
    "field_descriptors": [
      {
        "id": "53b4b60eecdcc45412000e8f",
        "type": "radios",
        "weight": 0,
        "label": "Rate the session content",
        "validation": {
          "required": true
        },
        "option_descriptors": [
          {
            "id": "53d1e7ccecdcc479c3002127",
            "label": "Excellent"
          },
          {
            "id": "53d1e7ccecdcc479c3002128",
            "label": "Good"
          },
          {
            "id": "53d1e7ccecdcc479c3002129",
            "label": "Average"
          },
          {
            "id": "53d1e7ccecdcc479c300212a",
            "label": "Fair"
          },
          {
            "id": "53d1e7ccecdcc479c300212b",
            "label": "Poor"
          }
        ]
      },
      {
        "id": "53b4b60eecdcc45412000e92",
        "type": "textarea",
        "weight": 1,
        "label": "Additional comments",
        "placeholder": "Please leave any comments."
      },
      ...
    ]
  }
]

These are all enabled surveys for the event.

HTTP Request

GET /api/surveys.json

Details

Publicly accessible Supports metadata

Sponsors

Sponsors for the event.

Get list of all sponsors

Example request

curl "https://foo.attendease.com/api/sponsors.json"

Example response

[
  {
    "id": "534f983becdcc464c4000004",
    "name": "Rackspace",
    "description": "The managed cloud company.",
    "level": "Platinum",
    "level_id": "5387c063cb20b8a078000005",
    "url": "http://rackspace.com",
    "logo_url": "http://eventbooking.uk.com/api/14/rackspace.png"
  },
  {
    "id": "53695f16ecdcc480c6000004",
    "name": "Search Discovery",
    "description": "A digital services agency.",
    "level": "Media",
    "level_id": "5387c069cb20b8a078000007",
    "url": "http://searchdiscovery.com",
    "logo_url": "http://eventbooking.uk.com/api/14/searchdiscovery.png"
  },
  ...
]

These are all sponsors for the event.

Supports metadata

HTTP Request

GET /api/sponsors.json

Details

Publicly accessible Supports metadata

Rooms

If an event is big enough it should have rooms. Session instances will be associated to these rooms.

Get a list of all rooms

Example request

curl "https://foo.attendease.com/api/rooms.json"

Example response

[
  {
    "capacity":420,
    "day_ids":[
      "52376b074aba5a0765000006",
      "52376b074aba5a0765000007",
      "52376b074aba5a0765000008",
      "52376b074aba5a0765000009",
      "52376b074aba5a076500000a"
    ],
    "filter_item_ids":[
      "52376b074aba5a0765000071"
    ],
    "id":"52376b074aba5a0765000024",
    "name":"Ballroom BC",
    "venue_id":"52376b074aba5a0765000022"
  },
  {
    "capacity":420,
    "day_ids":[
      "52376b074aba5a0765000006",
      "52376b074aba5a0765000007",
      "52376b074aba5a0765000008",
      "52376b074aba5a0765000009",
      "52376b074aba5a076500000a"
    ],
    "filter_item_ids":[
      "52376b074aba5a0765000096",
      "52376b074aba5a0765000071"
    ],
    "id":"52376b074aba5a0765000025",
    "name":"Ballroom D",
    "venue_id":"52376b074aba5a0765000022"
  }
  ...
]

These are all the rooms available for the event.

Supports metadata

HTTP Request

GET /api/rooms.json

Details

Publicly accessible Supports metadata

Venues

A venue contains many rooms, just like in real life.

Get a list of all venues

Example request

curl "https://foo.attendease.com/api/venues.json"

Example response

[
  {
    "id":"52e9f10d633a65bbdb00000a",
    "primary":true,
    "name":"AT&T Conference Center",
    "address":{
      "address1":"1900 University Ave.",
      "address2":"",
      "city":"Austin",
      "country":"United States",
      "latitude":"30.2824039",
      "longitude":"-97.74034189999998",
      "state":"Texas",
      "zip":"78705"
    },
    "room_ids":[
      "52e9f12d633a65bbdb00003e",
      "52e9f12d633a65bbdb000043",
      "52e9f12d633a65bbdb00004d",
      "52e9f12d633a65bbdb000051",
      "52e9f12d633a65bbdb000056",
      "52e9f12d633a65bbdb00005a",
      "52e9f12d633a65bbdb000064",
      "52e9f12d633a65bbdb000070",
      "52e9f12d633a65bbdb000074",
      "52e9f12e633a65bbdb00009d"
    ]
  },
  {
    "id":"52e9f10f633a65bbdb000021",
    "primary":false,
    "name":"Wanderlust",
    "address":{
      "address1":"206 E 4th St.",
      "address2":"",
      "city":"Austin",
      "country":"United States",
      "latitude":"30.265971",
      "longitude":"-97.74160599999999",
      "state":"Texas",
      "zip":"78701"
    },
    "room_ids":[
      "52e9f130633a65bbdb000165"
    ]
  },
  {
    "id":"52e9f10f633a65bbdb000023",
    "primary":false,
    "name":"Blackheart",
    "address":{
      "address1":"86 Rainey St.",
      "address2":"",
      "city":"Austin",
      "country":"United States",
      "latitude":"30.259694",
      "longitude":"-97.73872699999998",
      "state":"Texas",
      "zip":"78701"
    },
    "room_ids":[
      "52e9f132633a65bbdb0001f6"
    ]
  }
]

These are all the venues available for the event.

HTTP Request

GET /api/venues.json

Details

Publicly accessible Supports metadata

Filters

When an event has a lot of sessions we need to break them down and make them filterable.

Get list of all filters

Example request

curl "https://foo.attendease.com/api/filters.json"

Example response

[
  {
    "id":"51647527ecdcc4d8a9000048",
    "name":"Audience",
    "colour":"#2d6e90",
    "filter_items":[
      {
        "id":"51647527ecdcc4d8a9000050",
        "name":"Application Developer",
        "colour":"#21516a"
      },
      {
        "id":"51647527ecdcc4d8a900008f",
        "name":"Graphic Designer",
        "colour":"#183c4f"
      }
    ]
  },
  {
    "id":"51647527ecdcc4d8a9000049",
    "name":"Level",
    "colour":"#4fb56c",
    "filter_items":[
      {
        "id":"51647527ecdcc4d8a9000051",
        "name":"Beginner",
        "colour":"#419559"
      },
      {
        "id":"51647527ecdcc4d8a900005e",
        "name":"Advanced",
        "colour":"#347747"
      },
      {
        "id":"51647527ecdcc4d8a9000068",
        "name":"Intermediate",
        "colour":"#2a6039"
      },
      {
        "id":"51647528ecdcc4d8a900009b",
        "name":"General Audience",
        "colour":"#245231"
      }
    ]
  },
  {
    "id":"51647527ecdcc4d8a900004a",
    "name":"Type",
    "colour":"#bf4e26",
    "filter_items":[
      {
        "id":"51647528ecdcc4d8a900009c",
        "name":"Lab",
        "colour":"#a04120"
      },
      {
        "id":"5164752aecdcc4d8a90000e0",
        "name":"Session",
        "colour":"#82351a"
      },
      {
        "id":"51647563ecdcc4d8a90002ad",
        "name":"Keynote",
        "colour":"#652914"
      }
    ]
  },
  ...
]

These are all the filters available for the event. Sessions and Rooms can use these filters to add valuable metadata for displaying and filtering.

HTTP Request

GET /api/filters.json

Details

Publicly accessible Supports metadata

Content

Access the website content that was set in the Attendease admin.

Get list of all event content

Example request

curl "https://foo.attendease.com/api/filters.json"

Example response

[
  {
    "id":"53176633633a659c8c000126",
    "name":"Marquee",
    "section":"website",
    "contents":[
      {
        "key":"event_marquee_background_image_url",
        "type":"image url",
        "data":"https://attendease.com/images/background.jpg"
      },
      {
        "key":"event_marquee_title",
        "type":"string",
        "data":"The title goes here"
      },
    ]
  }
]

This is all the content for the event. They content groups have a name, section and content items (contents). The name is used for grouping similar content items. The section can be either website, mobile or email.

HTTP Request

GET /api/content.json

Details

Publicly accessible Supports metadata

Parameters

You can also get the content for specific sections. The section can be either website, mobile or email.

GET /api/content/website.json

GET /api/content/mobile.json

GET /api/content/email.json

Organization API

For Enterprise customers, we offer an Organization API to access events and attendees at the organization level.

API Endpoint

Your API Endpoint uses your organization’s subdomain.

e.g. https://foo.attendease.org/

Authentication

For API calls involving sensitive data, requests will require authentication using HMAC-SHA1 request signing. You will be provided with an Access Key ID and a Secret Access Token. The Secret Access Token is used to sign the request, but will never itself be transmitted. This token must be kept private and safe.

The request signature is sent using an HTTP header as part of the request. To generate the signature, you must first create a canonical string based some specific HTTP headers that are in the request.

canonical_string = 'content-type,content-MD5,request URI,timestamp'

Item Explanation
content-type The Content-Type header you’re sending
content-MD5 A base-64 encoded MD5 hash of the request body (for PUT and POST)
request URI The requested path (immediately after the hostname)
timestamp An RFC 1123 date

Example:

If we’re requesting GET https://foo.attendease.org/api/v2/events.json, we’d prepare our canonical string as follows:

Item Explanation
content-type application/json
request URI /api/v2/events.json
timestamp Tue, 16 Jun 2015 07:49:47 GMT
digest = OpenSSL::Digest.new('sha1')
signature = Base64.strict_encode64(OpenSSL::HMAC.digest(digest, secret_key, canonical))

Example Request

GET /api/v2/events.json HTTP/1.1
Host: foo.attendease.org
Date: Tue, 16 Jun 2015 07:58:34 GMT
Content-Type: application/json
Authorization: APIAuth 556d034a32d4a42201000001:OqOq+YBMdqqib70HNbKnOZDPXMQ=

The canonical string would be:

canonical = "application/json,,/api/v2/events.json,Tue, 16 Jun 2015 07:49:47 GMT"

Next, the authorization header needs to be signed. For this, the secret access token is needed. This will be easiest to use an OpenSSL library, of which there are many.

Finally, an Authorization header has to be added to your request:

Authorization: APIAuth access_key:signature

Where access_key is your access key ID for your secret access token, and signature is the HMAC signature.

If you are writing your own client, use the following sample to test that your signing algorithm is producing the correct data:

Given a canonical string of:

application/json,,/api/v2/attendees.json,Thu, 04 May 2017 00:00:00 GMT

And an Access Key ID of foo and a Secret Access Token of bar, your Authorization header should be:

APIAuth foo:0qQ6OkUhZ6wZOoYIsKEuGAed3Xk=

GET /api/v2/attendees.json HTTP/1.1
Host: whatever.attendease.org
Date: Thu, 04 May 2017 00:00:00 GMT
Content-Type: application/json
Authorization: APIAuth foo:0qQ6OkUhZ6wZOoYIsKEuGAed3Xk=

The entire request would look like what we have to the right:

If your Authorization header looks different, ensure that your canonical string is exactly like what we have above, and that you’re signing it with the secret key of bar.

Pagination

All API calls within the Organization API return paginated results.

Example response

{
  "pagination": {
    "total_records": 992,
    "num_records":   42,
    "page_size":     50,
    "page_count":    20,
    "page":          20
  },
  "foos": [ { "bar": "bat"}, { "bar": "baz" } ]
}

The structure is as follows:

Key Description
total_records total number of records returned
num_records number of records in this page (<= page_size)
page_size number of records per page (default 50)
page_count number of pages total
page current page

Optional parameters:

Key Description
records_per_page Can be an integer between 1 and 100; default: 50

Metadata filtering

You can filter results using meta information that you have added to your resources. The form is:

?meta[foo]=bar

If you have multiple meta fields, you can narrow the search by including additional meta searches:

?meta[foo]=bar&meta[bat]=baz

This would return events who have meta fields of both foo: bar and bat: baz.

If your meta fields use boolean values, you can do:

?meta[foo]=true

If you needed to search for a literal string of ‘true’ or 'false’, include single quotes around the value:

?meta[foo]='true'

Errors

Example request

curl "https://foo.attendease.org/api/v2/foobar.json"

Example response

HTTP Status 404

{"error":"Resource not found."}

When an error is encountered by Attendease, all calls within the Organization API return a HTTP status code and a JSON structure containing a descriptive message.

Business Units

Get business units and sub-business units

Example request

curl "https://foo.attendease.org/api/v2/business_units.json"

Example response

{
  "organizations": [
    [ 0] {
          "id": "ff433d5d-85a3-510f-8868-618b7b803624",
          "name": "My First Business Unit",
          "subdomain": "first-bu",
          "api_base_url": "https://first-bu.attendease.org/api/v2",
          "parent_id": "bd55ff27-37a2-516d-a27b-b45ff40c68bc",
          "published": false
        },
    [ 1] {
          "id": "84234894-b813-539a-8ce4-3b5ce6682b85",
          "name": "My First Sub-Business Unit",
          "subdomain": "first-sub-bu",
          "api_base_url": "https://first-sub-bu.attendease.org/api/v2",
          "parent_id": "ff433d5d-85a3-510f-8868-618b7b803624",
          "published": true
        },
    {...}
  ],
  "pagination": {
    "total_records":1000,
    "num_records":50,
    "page_size":50,
    "page_count":20,
    "page":1
  }
}

Empty sets appear like this (see also pagination, above):

{
  "organizations": [],
  "pagination": {
    "total_records":0,
    "num_records":0,
    "page_size":50,
    "page_count":0,
    "page":1
  }
}

The business unit listing will return all descendants of the organization or business unit in question.

HTTP Request

GET /api/v2/business_units.json

Response

An array of organizations will be returned representing the descendant business units and sub-business units.

The properties of each element are as follows:

Key Description
id UUID of the business unit or sub-business unit
name name of the business unit or sub-business unit
subdomain subdomain prefix of the business unit or sub-business unit
api_base_url URL to use to make API calls to this business unit or sub-business unit
parent_id UUID of the parent business unit or organization
published boolean indicating if there is a published portal website

Event

Get events

Example request

curl "https://foo.attendease.org/api/v2/events.json"

Example response

{
  "events": [
    {
      "id":"555ea1a0f6a30806110006ac",
      "created_at": "2015-07-21T23:34:49Z",
      "updated_at": "2015-08-13T21:21:24Z",
      "name":"Event Name",
      "subdomain":"eventname",
      "type":"event",
      "primary_venue": {
        "id": "55fafc414be5ddda64007afe",
        "name": "The Crew",
        "address": {
          "id": "55fafc414be5ddda64007aff",
          "address1": "131 Water St",
          "address2": "",
          "city": "Vancovuer",
          "zip": "V6B1A7",
          "state": "British Columbia",
          "state_iso": "BC",
          "country": "Canada",
          "country_iso": "CA",
          "latitude": "49.2841254",
          "longitude": "-123.1073584"
        }
      },
      "cnames":[],
      "third_party_registration":false,
      "third_party_url":"",
      "start_time":"2015-11-21T16:00:00Z",
      "end_time":"2015-11-22T01:00:00Z",
      "date_format_string":"%B %e, %Y",
      "time_format_string":"%H:%M",
      "time_zone":"Pacific Time (US & Canada)",
      "tags":["ondemand"],
      "archived":false,
      "url":"https://eventname.attendease.com/",
      "description": "Event description",
      "days": [
        {
          "id":"555ea1a0f6a30806110006b1",
          "date":"2015-11-21",
          "start_time":"08:00",
          "end_time":"17:00",
          "timezone_name":"Pacific Time (US & Canada)",
          "timezone_tzinfo":"America/Los_Angeles",
          "timezone_offset":"-08:00",
          "timezone_abbreviation":"PST",
          "start_utc":"2015-11-21T16:00:00+00:00",
          "end_utc":"2015-11-22T01:00:00+00:00",
          "date_formatted":"November 21, 2015",
          "start_time_formatted":"08:00",
          "end_time_formatted":"17:00"
        }
      ],
      "meta":{"region":"North America","visible":false}
    }, {...}
  ],
  "pagination": {
    "total_records":1000,
    "num_records":50,
    "page_size":50,
    "page_count":20,
    "page":1
  }
}

Example response

Empty sets appear like this (see also pagination, above):

{
  "events": [],
  "pagination": {
    "total_records":0,
    "num_records":0,
    "page_size":50,
    "page_count":0,
    "page":1
  }
}

By default, the event listing will return all current and upcoming events. The results can be filtered using a variety of methods.

HTTP Request

/api/v2/events.json

Filter: Tags

Multiple tags can be specified to return events matching any of the supplied tags.

e.g.

GET /api/v2/events.json?tags[]=foo&tags[]=bar

Filter: Event Status

Events can be filtered by predefined statuses using the ?status= parameter. Supported statuses are:

Status Description
active Events that have started or haven’t yet started (default)
over Events that have ended (but not archived)
upcoming Events that are upcoming (haven’t yet started)
in-progress Events that have started but not yet finished
archived Archived events
all Past, current, and future events (excludes archived)

e.g.

GET /api/v2/events.json?status=in-progress

Filter: since

the filter “since” is

An ISO8601 UTC date string in the form of [YYYY]-[MM]-[DD]T[HH]:[MM]:[SS]Z denoting the events start date and time. The result will return events that start on or after this date. Example:

GET /api/v2/events.json?since=2015-05-05T00:00:00Z

Filter: before

An ISO8601 UTC date string in the form of [YYYY]-[MM]-[DD]T[HH]:[MM]:[SS]Z denoting the events end date and time. The result will return events that end before this date. Example:

GET /api/v2/events.json?before=2015-09-05T00:00:00Z

Filter: created_after

An ISO8601 UTC date string in the form of [YYYY]-[MM]-[DD]T[HH]:[MM]:[SS]Z denoting the events creation date and time. The result will return events that were created on or after this date. Example:

GET /api/v2/events.json?created_after=2015-05-05T00:00:00Z

Filter: updated_after

An ISO8601 UTC date string in the form of [YYYY]-[MM]-[DD]T[HH]:[MM]:[SS]Z denoting the events last update date and time. The result will return events that were updated on or after this date. Example:

GET /api/v2/events.json?updated_after=2015-05-05T00:00:00Z

Filter: metadata

See Metadata filtering above.

Filter: has_schedule

Use the has_schedule flag (true or false) to return events that have or do not have an associated schedule.

GET /api/v2/events.json?has_schedule=true

Filter: on_demand

Use the on_demand flag (true or false) to return events that have or do not have “Enable On Demand” set in their Media Options

GET /api/v2/events.json?on_demand=true

Update event metadata

Example payload

{
  "meta": {
    "foo": "red",
    "bar": [ "apple", "banana" ],
    "bat": true,
    "baz": false
  }
}

Events can be updated, though currently only on their metadata sets. You must pass a full metadata object as your payload.

PUT /api/v2/events/<id>

Member

Get member

Get the information for a single member of your organization, including a collection of their associated attendee records. Note that <id> in the request is the member_id value returned for each record in the attendees.json call.

HTTP Request

GET /api/v2/members/<id>

Example request

curl "https://foo.attendease.org/api/v2/members/<id>"

Example response

{
  "id":"ca147fbc-d3ed-4b6f-b354-96752763d084",
  "first_name":"Ygg",
  "last_name":"Wztm",
  "email":"ogemljj888axvesadoiv@private.attendease.com",
  "profile":{
    "profile_image_url":"https://s3.ca-central-1.amazonaws.com/attendease-cdn/images/user-placeholder-image.png"
  },
  "form_field_answers":[],
  "event_ids":[
    "698ce75e-1055-4204-b1a3-c64a9a40396a"
  ],
  "partner_types":[],
  "maintenance":false,
  "email_verified":false,
  "pii_consented":false,
  "custom_form_filings":[],
  "attendees":[
    {
      "id":"2a03ef08-2e28-45ba-9d13-a36fc288d22d",
      "member_id":"ca147fbc-d3ed-4b6f-b354-96752763d084",
      "event_id":"698ce75e-1055-4204-b1a3-c64a9a40396a",
      "event_name":"My Awesome Event",
      "first_name":"Ygg",
      "last_name":"Wztm",
      "email":"ogemljj888axvesadoiv@private.attendease.com",
      "profile":{
        "company":"",
        "title":"",
        "bio":"",
        "profile_image_url":"https://www.gravatar.com/avatar/fe8216b42380683f8f72d76b12d59992?s=200&d=mm",
        "company_logo_url":"",
        "facebook":"",
        "twitter":"",
        "googleplus":"",
        "linkedin":""
      },
      "pass_id":"99709670-4790-4aed-a157-b9569c11716a",
      "pass_name":"Event Pass",
      "addon_passes":[],
      "registration_code":"",
      "pricing_group":"Public",
      "total_price":"0.0",
      "amount_paid":0,
      "amount_owing":0,
      "transaction_currency":"USD",
      "registered_at":"2018-02-02T13:21:02Z",
      "updated_at":"2018-02-02T13:21:03Z",
      "checked_in_at":"",
      "cancelled_at":nil,
      "registered":true,
      "in_progress":false,
      "registration_status":"Registered",
      "parent_attendee_id":"",
      "additional_passes":0,
      "meta":{},
      "registration_form_filings":[
        {
          "id":"113b8688-a296-4609-885d-5020e2535d7f",
          "registration_form_id":"dd0af4a5-bf87-4682-a177-d99dbd4847bc",
          "answers":{
            "School/University/Institution Name":"McGill University",
            "Education Segment":"Masters Degree"
          }
        }
      ],
      "survey_filings":[],
      "checkins":[],
      "pass":{
        "id":"99709670-4790-4aed-a157-b9569c11716a",
        "name":"Event Pass",
        "pass_type":"primary",
        "description":nil,
        "weight":0,
        "available":true,
        "used":true,
        "days_in_effect":[
          "2018-02-06"
        ],
        "price":0
      },
      "auto_submitted":false
    }
  ]
}

Obfuscate member

This allows you to obfuscate all the personally identifiable information for a member, including all their attendee records. It will replace first and last name with ‘DELETED’, and will replace the account email address with a randomized address that has a @deleted.attendease.com suffix. It will also delete any form field answers that were entered manually by the attendee.

Example request

curl "https://foo.attendease.org/api/v2/members/<id>/obfuscate"

Example response

{
  "id":"ca147fbc-d3ed-4b6f-b354-96752763d084",
  "first_name":"DELETED",
  "last_name":"DELETED",
  "email":"12312-123-1212312-21122@deleted.attendease.com",
  "profile":{
    "profile_image_url":"https://s3.ca-central-1.amazonaws.com/attendease-cdn/images/user-placeholder-image.png"
  },
  "form_field_answers":[],
  "event_ids":[
    "698ce75e-1055-4204-b1a3-c64a9a40396a"
  ],
  "partner_types":[],
  "maintenance":false,
  "email_verified":false,
  "pii_consented":false,
  "custom_form_filings":[],
  "attendees":[
    {
      "id":"2a03ef08-2e28-45ba-9d13-a36fc288d22d",
      "member_id":"ca147fbc-d3ed-4b6f-b354-96752763d084",
      "event_id":"698ce75e-1055-4204-b1a3-c64a9a40396a",
      "event_name":"My Awesome Event",
      "first_name":"DELETED",
      "last_name":"DELETED",
      "email":"12-123-1212312-21122@deleted.attendease.co",
      "profile":{
        "company":"",
        "title":"",
        "bio":"",
        "profile_image_url":"https://www.gravatar.com/avatar/fe8216b42380683f8f72d76b12d59992?s=200&d=mm",
        "company_logo_url":"",
        "facebook":"",
        "twitter":"",
        "googleplus":"",
        "linkedin":""
      },
      "pass_id":"99709670-4790-4aed-a157-b9569c11716a",
      "pass_name":"Event Pass",
      "addon_passes":[],
      "registration_code":"",
      "pricing_group":"Public",
      "total_price":"0.0",
      "amount_paid":0,
      "amount_owing":0,
      "transaction_currency":"USD",
      "registered_at":"2018-02-02T13:21:02Z",
      "updated_at":"2018-02-02T13:21:03Z",
      "checked_in_at":"",
      "cancelled_at":nil,
      "registered":true,
      "in_progress":false,
      "registration_status":"Registered",
      "parent_attendee_id":"",
      "additional_passes":0,
      "meta":{},
      "registration_form_filings":[
        {
          "id":"113b8688-a296-4609-885d-5020e2535d7f",
          "registration_form_id":"dd0af4a5-bf87-4682-a177-d99dbd4847bc",
          "answers":{
            "School/University/Institution Name":"",
            "Education Segment":"Masters Degree"
          }
        }
      ],
      "survey_filings":[],
      "checkins":[],
      "pass":{
        "id":"99709670-4790-4aed-a157-b9569c11716a",
        "name":"Event Pass",
        "pass_type":"primary",
        "description":nil,
        "weight":0,
        "available":true,
        "used":true,
        "days_in_effect":[
          "2018-02-06"
        ],
        "price":0
      },
      "auto_submitted":false
    }
  ]
}

This is useful when processing GDPR requests to delete a member’s data from your organization. Not that this doesn’t actually delete any of the member or attendee objects in order to maintain attendance statistics and the like.

CAUTION: this is a destructive, one-way call. It is therefore advisable to do a “dry run” before performing the actual obfuscation (see the “Obfuscation Dry Run” section below)

Note that <id> in the request is the member_id value returned for each record in the attendees.json call.

HTTP Request

PUT /api/v2/members/<id>/obfuscate

Obfuscation Dry Run

To do a dry run, do not pass any parameters to the method. The output will return the member, much like the “Get Member” call. However, if the member cannot be obfuscated (because they have a future pass or an outstanding balance) then errors to that effect will be returned in the output.

Actual Obfuscation

To actually perform the obfuscation pass ?obfuscate=true as a query string in the URL.

CAUTION: this is a destructive, one-way call. It is therefore advisable to do a “dry run” before performing the actual obfuscation (see the “Obfuscation Dry Run” section above)

Attendees

Get attendees

Example request

curl "https://foo.attendease.org/api/v2/attendees.json"

Example response

{
  "attendees": [
    {
      "id": "555ea1a0f6a30806110006b1",
      "member_id": "555ea1a0f6a30806110006b1",
      "first_name": "john",
      "last_name": "doe",
      "email": "jdoe@email.com",
      "registered_at": "2015-11-21T16:00:00+00:00",
      "updated_at": "2015-11-21T16:00:00+00:00",
      "meta": {"region":"North America","visible":false},
      "checked_in_at": "2015-11-21T16:00:00+00:00",
      "event_id": "",      
    },
    {...}
  ],
  "pagination": {
    "total_records":1000,
    "num_records":50,
    "page_size":50,
    "page_count":20,
    "page":1
  }
}

Example response

Empty sets appear like this (see also pagination, above):

{
  "attendees": [],
  "pagination": {
    "total_records":0,
    "num_records":0,
    "page_size":50,
    "page_count":0,
    "page":1
  }
}

The attendee listing allows you to retrieve registered attendees across all events within the organization. Filters may be used to narrow the focus of the results.

HTTP Request

GET /api/v2/attendees.json

Filters: registered_before, registered_after

An ISO8601 UTC date string in the form of [YYYY]-[MM]-[DD]T[HH]:[MM]:[SS]Z denoting the registration date and time. The result will return attendees registered before or after the date provided (inclusive of the passed date itself).

GET /api/v2/attendees.json?registered_before=2015-05-05T00:00:00Z

GET /api/v2/attendees.json?registered_after=2015-05-05T00:00:00Z

Filters: modified_after

An ISO8601 UTC date string in the form of [YYYY]-[MM]-[DD]T[HH]:[MM]:[SS]Z denoting the modification date and time of the attendee. The result will return attendees modified after after the date provided (inclusive of the passed date itself).

GET /api/v2/attendees.json?modified_after=2015-05-05T00:00:00Z

Filters: registration_status

You can request a list of attendees whose registration status is one of the following:

GET /api/v2/attendees.json?registration_status=registered

GET /api/v2/attendees.json?registration_status=cancelled

GET /api/v2/attendees.json?registration_status=in-progress

Filters: attended

Only return attendees who have been checked into (or not) an event.

GET /api/v2/attendees.json?attended=true

GET /api/v2/attendees.json?attended=false

Filter: metadata

See Metadata filtering above.

Scoping

The attendees listing can be scoped to an event or a session time slot.

To scope to an event, you will need the event_id:

GET /api/v2/events/__event_id__/attendees.json

To scope to a session time slot you will need to know both the session_id and timeslot_id.

GET /api/v2/events/__event_id__/sessions/__session_id__/instances/__timeslot_id__/attendees.json

Requesting more attendee data

Example response

{
  "attendees": [
    {
      "id": "555ea1a0f6a30806110006b1",
      "first_name": "john",
      "last_name": "doe",
      "email": "jdoe@email.com",
      "profile": {
        "company": "",
        "title": "",
        "bio": "",
        "profile_image_url": "https://www.gravatar.com/avatar/0e711f9b902464a587132052458f3116?s=200&d=mm",
        "company_logo_url": "",
        "facebook": "",
        "twitter": "",
        "googleplus": "",
        "linkedin": ""
      },
      "registered_at": "2015-11-21T16:00:00+00:00",
      "updated_at": "2015-11-21T16:00:00+00:00",
      "meta": {"region":"North America","visible":false},
      "checked_in_at": "2015-11-21T16:00:00+00:00",
      "event_id": "",
      "registration_form_filings": [
        {
          "id": "555ea1a0f6a30806110006ac",
          "form_id": "51e42fe7ecdcc4d44f000002",
          "answers": [
            {"key": "value"},
            {...}
          ]
        },
        {...}
      ],
      "survey_filings": [
        {
          "id": "555ea1a0f6a30806110006ac",
          "form_id": "51e42fe7ecdcc4d44f000002",
          "answers": [
            {"key": "value"},
            {...}
          ]
        },
        {...}
      ]
    },
    {...}
  ],
  "pagination": {
    "total_records":1000,
    "num_records":50,
    "page_size":50,
    "page_count":20,
    "page":1
  }
}

You can request more data from the API when querying on your attendees:

Update attendee metadata

Example payload

{
  "meta": {
    "foo": "red",
    "bar": [ "apple", "banana" ],
    "bat": true,
    "baz": false
  }
}

Attendees can be updated, though currently only on their metadata sets. You must pass a full metadata object as your payload.

HTTP Request

PUT /api/v2/attendees/<id>

Check-ins

Check-ins are attached to attendees and can be created with either the “Event” or “Instance” type.

“Event” check-ins are usually the result of checking in to an event (like an attendee would do in-person when picking up their conference badge).

“Instance” checkins are the result of checking in to a particular session time slot at an event (like an attendee would do when walking into a particular event session).

Create a new check-in

Example payload (Event Checkin)

{
  "checkins": [
    {
      "type": "Event",
      "data": {},
      "checked_in_at": "2018-01-17T01:41:37Z"
    }
  ]
}

Example payload (Session Instance Checkin)

{
  "checkins": [
    {
      "type": "Instance",
      "data": {
        "instance_id": "d8ccc01b-2f1e-404b-b7b8-1ad5c4552ef2"
      },
      "checked_in_at": "2018-01-17T01:42:07Z"
    }
  ]
}

Example successful response

{
  "status": "ok"
}

Example failed response

{
  "status": "failed",
  "reason": "invalid payload"
}

Creating an Event or Instance check-in for an attendee.

HTTP Request

POST /api/v2/attendees/<attendee id>/checkins.json

Canceling a check-in

Example payload (Event Checkin)

{
  "checkins": [
    {
      "type": "Event",
      "cancel": true,
      "data": {}
    }
  ]
}

Example payload (Session Instance Checkin)

{
  "checkins": [
    {
      "type": "Instance",
      "cancel": true,
      "data": {
        "instance_id": "d8ccc01b-2f1e-404b-b7b8-1ad5c4552ef2"
      }
    }
  ]
}

Example successful response

{
  "status": "ok"
}

Example failed response

{
  "status": "failed",
  "reason": "invalid payload"
}

Canceling an Event or Instance check-in for an attendee.

HTTP Request

POST /api/v2/attendees/<attendee id>/checkins.json

Partner

Get partner

Get all the information for any speaker, sponsor or exhibitor that has submitted an application in your organization with a certain email address.

HTTP Request

GET /api/v2/partners/<email>

Example request

curl "https://foo.attendease.org/api/v2/partners/<email>"

Example response

[
  {
    "id":"a5a512-ca35-4428-bed7-e332865e3dee",
    "member_id":null,
    "created_at":"2018-04-03T07:53:01Z",
    "custom_form_id":"f60ee539-d65f-4084-b12fa-804180c43316",
    "updated_at":"2018-06-06T19:10:59Z",
    "answers_humanized":
    [
      {
        "type":"text",
        "mapping":{
          "model":"presenter",
          "attribute":"first_name"
        },
        "label":"First name",
        "answer":"Jim"
      },
      {
        "type":"text",
        "mapping":
        {
          "model":"presenter",
          "attribute":"last_name"
        },
        "label":"Last name",
        "answer":"Jones"
      },
      {
        "type":"text",
        "mapping":{
          "model":"presenter",
          "attribute":"email"
        },
        "label":"Email",
        "answer":"jim@jones.com"
      }
    ]
  }
]

Obfuscate partner

This allows you to obfuscate all the personally identifiable information for a partner. It will replace first name, last name and email with ‘DELETED’. It will also delete any form field answers that were entered manually during the application process.

Example request

curl "https://foo.attendease.org/api/v2/partners/<id>/obfuscate"

Example response

[
  {
    "id":"a5a512-ca35-4428-bed7-e332865e3dee",
    "member_id":null,
    "created_at":"2018-04-03T07:53:01Z",
    "custom_form_id":"f60ee539-d65f-4084-b12fa-804180c43316",
    "updated_at":"2018-06-06T19:10:59Z",
    "answers_humanized":
    [
      {
        "type":"text",
        "mapping":{
          "model":"presenter",
          "attribute":"first_name"
        },
        "label":"First name",
        "answer":"DELETED"
      },
      {
        "type":"text",
        "mapping":
        {
          "model":"presenter",
          "attribute":"last_name"
        },
        "label":"Last name",
        "answer":"DELETED"
      },
      {
        "type":"text",
        "mapping":{
          "model":"presenter",
          "attribute":"email"
        },
        "label":"Email",
        "answer":"DELETED"
      }
    ]
  }
]

This is useful when processing GDPR requests to delete a member’s data from your organization. Not that this doesn’t actually delete any of the member or attendee objects in order to maintain attendance statistics and the like.

CAUTION: this is a destructive, one-way call. It is therefore advisable to get the partner (see “Get Partner”) before performing the actual obfuscation.

HTTP Request

PUT /api/v2/partners/<email>/obfuscate

Sessions

Get sessions

Example request

curl "https://<org_api_endpoint>/api/v2/events/<event_id>/sessions.json"

Example response

{
  "sessions": [
    {
      "id":"555ea1a0f6a30806110006ac",
      "name":"Event Name",
      "code":"eventname",
      "meta":{ ... },
      "instances": [
        {
          "id": "55fb28d94be5ddda6400f8c0",
          "date": "2015-11-18",
          "time": "09:00",
          "duration": 180,
          "attendee_ids": [ ],
          "start_time_utc": "2015-11-18T17:00:00Z",
          "end_time_utc": "2015-11-18T20:00:00Z"
        }
      ],
    }, {...}
  ],
  "pagination": {
    "total_records":1000,
    "num_records":50,
    "page_size":50,
    "page_count":20,
    "page":1
  }
}

Example response

Empty sets appear like this (see also pagination, above):

{
  "sessions": [],
  "pagination": {
    "total_records":0,
    "num_records":0,
    "page_size":50,
    "page_count":0,
    "page":1
  }
}

HTTP Request

/api/v2/events/<event_id>/sessions.json

By default, the session listing will return all sessions in an event. The results can be filtered using a variety of methods.

Filter: with_instances

Specify ?with_instances=yes to only include sessions that have instances (time slots).

e.g.

GET /api/v2/events/<event_id>/sessions.json?with_instances=yes

Filter: Instance Status

Events can be filtered by predefined statuses using the ?status= parameter. Supported statuses are:

Status Description
active Instances that have started or haven’t yet started
over Instances that have ended
upcoming Instances that are upcoming (haven’t yet started)
in-progress Instances that have started but not yet finished
on-demand Instances that have “Enable On Demand” checked on their parent session
all Past, current, and future instances (default)

e.g.

GET /api/v2/events/foo/sessions.json?status=in-progress

Filter: metadata

See Metadata filtering above.

Get all event sessions attendance

Example request

curl "https://foo.attendease.org/api/v2/session_attendance.json"

Example response

The above command returns JSON structured like this (for a descriptions of the returned attendee structure see also attendees, above):

{
  "session_attendance": [
    {
      "session": {
        "id": "5570e4db32d4a4772e0000ab",
        "title": "session title",
        "code": "session code",
        "meta": {"region":"North America","visible":false}
      },
      "attendees": [ {...} ]
    },
    (...)
  ]
}

The session attendance listing allows you to retrieve registered attendees from all sessions across all events within the organization.

HTTP Request

GET /api/v2/session_attendance.json

Update session metadata

Example payload

{
  "meta": {
    "foo": "red",
    "bar": [ "apple", "banana" ],
    "bat": true,
    "baz": false
  }
}

Sessions can be updated, though currently only on their metadata sets. You must pass a full metadata object as your payload.

HTTP Request

PUT /api/v2/events/<event_id>/sessions/<session_id>.json

Contact Lists

Get list of contact lists

If a contact list has managed set to true, the organization owner will not be able to manage the contact list via the Attendease Dashboard, it can only be modified via this API.

Contact lists must have a unique name and external_id for each endpoint.

Example response

{
  "contact_lists": [
    {
      "id": "555ea1a0f6a30806110006b1",
      "name": "My First Contact List",
      "managed": false,
      "external_id": "0123456789",
    },
    {
      "id": "555ea1a0f6a30806110006b2",
      "name": "My Second Contact List",
      "managed": true,
      "external_id": "1234567890",
    },      
  ],
  "pagination": {
    "total_records":2,
    "num_records":2,
    "page_size":50,
    "page_count":1,
    "page":1
  }
}

Empty sets appear like this (see also pagination, above):

{
  "contact_lists": [],
  "pagination": {
    "total_records":0,
    "num_records":0,
    "page_size":50,
    "page_count":0,
    "page":1
  }
}

HTTP Request

GET /api/v2/contact_lists.json

Create a new contact list

Example payload

{
  "contact_list": {
    "name": "My Third Contact List",
    "external_id": "2345678901",
    "managed": true
  }
}

Example response

{
  "id": "d3e20ab4-210b-4e13-a5e8-6bd277fe13c2",
  "name": "My Third Contact List",
  "external_id": "2345678901",
  "managed": true  
}

Contact lists must have a unique name and external_id for each endpoint.

HTTP Request

POST /api/v2/contact_lists.json

Update an existing contact list

You can update any field of an existing contact list provided name and external_id do not conflict with any other lists.

Example payload

{
  "contact_list": {
    "external_id": "3456789012",
    "managed": false
  }
}

Example success response

{
  "status": "ok"
}

Example failed response

{
  "errors": {
    "name": ["should be unique within your organization or business unit"],
    "external_id": ["should be unique within your organization or business unit"]
  }
}

HTTP Request

PUT /api/v2/contact_lists/<id>.json

Delete all contacts in a contact list

This method deletes all contacts in a contact list.

Example success response

{
  "status": "ok"
}

Example failed response

{
  "status": "failed",
  "reason": "only 5 contact(s) deleted. 10 remain(s)."
}

HTTP Request

DELETE /api/v2/contact_lists/<id>/delete_contacts.json

Delete a contact list

You can only delete an empty contact list (one that has no associated contacts).

Example success response

{
  "status": "ok"
}

Example failed response

{
  "status": "failed",
  "reason": "contact list is not empty"
}

HTTP Request

DELETE /api/v2/contact_lists/<id>.json

Contacts

Get contacts from a list

Contacts must have at least a value for email or sms. Furthermore, email, sms and external_id must be unique within a particular contact list.

Example response

{
  "contacts": [
    {
      "id": "555ea1a0f6a30806110006b1",
      "first_name": "Roger",
      "last_name": "Townsend",
      "email": "roger@who.com",
      "sms": "",
      "external_id": "0123456789",
    },
    {
      "id": "555ea1a0f6a30806110006b2",
      "first_name": "Pete",
      "last_name": "Daltrey",
      "email": "pete@who.com",
      "sms": "",
      "external_id": "1234567890",
    },      
  ],
  "pagination": {
    "total_records":2,
    "num_records":2,
    "page_size":50,
    "page_count":1,
    "page":1
  }
}

Empty sets appear like this (see also pagination, above):

{
  "contacts": [],
  "pagination": {
    "total_records":0,
    "num_records":0,
    "page_size":50,
    "page_count":0,
    "page":1
  }
}

HTTP Request

GET /api/v2/contact_lists/<contact-list-id>/contacts.json

Add contacts to a list

Contacts must have at least a value for email or sms. Furthermore, email, sms and external_id must be unique within a particular contact list.

If even one contact addition fails, the system will return an error even if some of the contacts were successfully added. The returned errors array (which matches the order and number of contacts in the payload) will provide an “ok” for successful additions or a hash with a reason for any failures.

Example payload

{
  "contacts": [{
    "first_name": "Keith",
    "last_name": "Enthwistle",
    "email": "keith@who.com",
    "sms": "",
    "external_id": "3456789012",
  },
  {
    "first_name": "John",
    "last_name": "Moon",
    "email": "john@who.com",
    "sms": "",
    "external_id": "4567890123",
  }
]}

Example success response

{
  "contacts": [{
    "first_name": "Keith",
    "last_name": "Enthwistle",
    "email": "keith@who.com",
    "sms": "",
    "external_id": "3456789012",
  },
  {
    "first_name": "John",
    "last_name": "Moon",
    "email": "john@who.com",
    "sms": "",
    "external_id": "4567890123",
  }]
}

Example failed response

{
  "status": "failed",
  "reason": "only 2 of 5 contacts were created.",
  "errors": [
    {
      "email": ["should be unique within your contact list"],
      "sms": ["should be unique within your contact list"],
      "external_id": ["should be unique within your contact list"]
    },
    "ok",
    {
      "email": ["should be unique within your contact list"],
      "sms": ["should be unique within your contact list"],
      "external_id": ["should be unique within your contact list"]
    },    
    {
      "email": ["is invalid"],      
    },
    "ok"
  ]
}

HTTP Request

POST /api/v2/contact_lists/<contact-list-id>/contacts.json

Update an existing contact

You can update any field of an existing contact provided email, sms and external_id do not conflict with any other contacts in the list.

Example payload

{
  "contact": {
    "first_name": "Bill",
    "last_name": "Barilco",
    "email": "bill@missing.com",
    "sms": "",
    "external_id": "4567890123",
  }
}

Example success response

{
  "status": "ok"
}

Example failed response

{
  "errors": {
    "email": ["should be unique within your contact list"],
    "sms": ["should be unique within your contact list"],
    "external_id": ["should be unique within your contact list"]
  }
}
{
  "errors": {
    "email": ["or sms should have a value"]
  }
}
{
  "errors": {
    "sms": ["or email should have a value"]
  }
}

HTTP Request

PUT /api/v2/contact_lists/<contact-list-id>/contacts/<id>.json

Delete a contact

Example success response

{
  "status": "ok"
}

Example failed response

{
  "status": "failed",
  "reason": "contact not found"
}

HTTP Request

DELETE /api/v2/contact_lists/<contact-list-id>/contacts/<id>.json