Requests and Responses

HTTP-based

Most methods to retrieve data from the Pigeonhole Live API require a GET request. API methods that require a particular HTTP method will return an error if not invoked using the correct style. HTTP Response Codes are meaningful.

info

All connections must be made over TLS 1.2.

Parameters

Some API methods take optional, or required, parameters. Keep in mind when making requests with parameters:

• Parameter values should be converted to UTF-8 and URL encoded.

Where noted, some API methods will return different results based on HTTP headers sent by the client. Where the same behavior can be controlled by both a parameter and an HTTP header, the parameter will take precedence.

info

The API uses an open schema model, which means the server will ignore any extra query parameters and request body properties.

Request IDs

Each API request has an associated request identifier. You can find this value in the response headers, under X-Request-Id.

tip

If you need to contact us about a specific request, providing the request identifier will ensure the fastest possible resolution.

Input validation

Don’t assume that your users will provide you with valid, trustworthy data.

Sanitize all data, checking for sane string lengths, valid file types, etc.

Pigeonhole Live attempts to sanitize data POSTed to our APIs, but a little client-side help goes a long way.

Whitelist the types of input that are acceptable to your application and discard everything that isn’t on the whitelist.

The body of a validation error response will be JSON in the following format:

{
  "code": 4500,
  "message": "The given data was invalid.",
  "errors": [
    {
      "field": "name",
      "message": "The length must be between 1 and 100 characters."
    },
    {
      "field": "lastName",
      "message": "The field is required."
    }
  ]
}

Filtering

The Pigeonhole Live API supports filtering of resource collections based upon associations by allowing query parameters that combine filter with the association name.

The filter query parameter is reserved to be used as the basis for any filtering strategy.

For example, the following is a request for all Pigeonholes with a particular status:

GET /v2/pigeonholes?filter[status]=live

Multiple filter values can be combined in a comma-separated list. For example:

GET /v2/pigeonholes?filter[status]=upcoming,live,ended

Furthermore, multiple filters can be applied to a single request:

GET /v2/pigeonholes?filter[status]=live,ended&filter[timezone]=Asia/Singapore

info

Unsupported filter names or values will be ignored.

Pagination

For designated GET requests the Pigeonhole Live API utilizes a cursor-based pagination.

We now accept an optional cursor and count query parameter described below.

Name	Type	Description
cursor	string	A cursor for use in pagination. It defines your place in the list. The value is a base64 encoded string as defined in RFC 4648 and it must be considered opaque; the implementation is subject to change.
count	int	A value for custom page max size. It defines how many items to return. The value accepts integers from 1-300 inclusive, with 30 as default if no value is set.

For example, the following is a request for the first page of Pigeonholes results:

GET /v2/pigeonholes

{
  "data": [...],
  "links": {
    "next": "https://api.pigeonholelive.com/v2/pigeonholes?cursor=Y3Vyc29yXzk0OA=="
  },
  "meta": {
    "perPage": 30,
    "nextCursor": "Y3Vyc29yXzk0OA==",
    "hasMore": true
  }
}

To get the next series of responses, you would add cursor to your query params:

GET /v2/pigeonholes?cursor=Y3Vyc29yXzk0OA==

{
  "data": [...],
  "links": {
    "next": "https://api.pigeonholelive.com/v2/pigeonholes?cursor=Y3Vyc29yXzEyMTc="
  },
  "meta": {
    "perPage": 30,
    "nextCursor": "Y3Vyc29yXzEyMTc=",
    "hasMore": true
  }
}

To set a custom page max size, you would add count to your query params:

GET /v2/pigeonholes?cursor=Y3Vyc29yXzk0OA==&count=10

{
  "data": [...],
  "links": {
    "next": "https://api.pigeonholelive.com/v2/pigeonholes?cursor=Y3Vyc29yXzEyMTc=&count=10"
  },
  "meta": {
    "perPage": 10,
    "nextCursor": "Y3Vyc29yXzEyMTc=",
    "hasMore": true
  }
}

The links object helps you to easily navigate the results.

Name	Type	Description
next	string	A link to the next set of results. The value is null if this set comprises the end of the list.

The meta object includes meta information described below.

Name	Type	Description
perPage	number	The current page max size regardless of the number of objects in the current set.
nextCursor	string	A cursor pointing to the next set of results. Include this cursor in the subsequent call in order to fetch the next page of the list. The value is null if this set comprises the end of the list.
hasMore	boolean	Whether or not there are more elements available after this set. If false, this set comprises the end of the list.

Errors

The Pigeonhole Live API uses standard HTTP status codes to indicate the success or failure of the API call. The body of the response will be JSON in the following format:

{
  "code": 1234,
  "message": "error description"
}

Error codes

The 4-digit error code identifies the type of error, for example, resource not found or missing required field. The following table describes the most common error codes.

Code	Error category	Description
5000	The server encounters an internal error.	Contact us with the returned X-Request-Id value in the response header for assistance.
6000	Invalid parameter value.	Request fails due to one or more invalid query parameters value.
7001	Malformed request	The request cannot be processed due to JSON syntax errors.
8000	Request exceeded limit	The max number of requests provided by the plan has been reached. Contact us to increase the limit.
9000	Unsupported feature	The requested resource or option is not supported by our API yet.
4500	Invalid format or value	The request cannot be processed due to an invalid field format or value. Read more in the input validation section.
4501	Authentication failed	Authentication fails due to invalid API authentication credentials. Check the authentication section.
4502	Not found	The specified resource cannot be found.
4503	Workspace not found	The workspace ID specified in the URL is not found or it is in the wrong format.
4504	Pigeonhole not found	The Pigeonhole ID specified in the URL is not found or it is in the wrong format.
4505	Subscription not found	The subscription ID is not found or it is in the wrong format.
4506	Profile filed not found	The Pigeonhole profile field ID is not found or it is in the wrong format.
4507	Registrants not available	The registrants feature is disabled in the given Pigeonhole.
4508	Attendees profiles not available	The Attendee profiles features is disabled in the given Pigeonhole.
4509	Session not found	The session ID specified in the URL is not found or it is in the wrong format.
4510	Registrant not found	The registrant ID or Code is not found or it is in the wrong format.
4511	One-Time token not found	The one-time token is not found or it is in the wrong format.
4512	Speaker not found	The speaker ID is not found or it is in the wrong format.