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.

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.

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.

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

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>

Attendees

Get attendees

Example request

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

Example response

{
  "attendees": [
    {
      "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": "",
      "registration_form_filings": [
        {
          "id": "555ea1a0f6a30806110006ac",
          "form_id": "51e42fe7ecdcc4d44f000002",
          "answers": [
            {"key": "value"},
            {...}
          ]
        },
        {...}
      ]
    },
    {...}
  ],
  "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: 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 timeslot.

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

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

To scope to a session timeslot 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

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>

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