REST Pub API: Event Registrations

This resource allows submission of registration information for events. Note this is a write-only resource, and for security reasons it does not support retrieval of registration information. This endpoint is designed to be used with custom registration forms hosted on external sites.

Only JSON media types for requests and responses are supported.

JSONP submission is allowed for older browsers that do not support Cross-Origin Resource Sharing (CORS) or cannot execute cross-domain HTTP POSTs.

The resource returns specific error codes for duplicate registrations (where individuals are identified by their combined first name, last name, and email), and also for situations where the event is full and is no longer accepting registrations.

After the registration period closes for an event, the API will return a 404 status code.

Resource URI

/api/2012-02-01/pub/resources/events/{EventID}/registrations/

General structure

{
   "Contact":{
      "FirstName":"Julie",
      "LastName":"Everett",
      "Email":"julie.everett@example.org",
      "PhoneWork":"+64 4 123 4567",
      "PhoneWork":"+64 4 987 6543",
      "Mobile":"+64 21 1234 5678",
      "Employment":{
         "OrganisationName":"Acme Industries Ltd",
         "Position":"General Manager",
         "Department":"Human Resources"
         "BusinessUnit":"TWI"
      },
      "SpecialDiet":"Vegetarian",
      "Disability":"Wheelchair",
   },
   "Comments":"Test comment"
}

Fields

Field	Description
Contact	A Contact structure (see below) describing the contact associated with the registration.
Comments	Unstructured text comments to be attached to the registration. String, up to 256 characters long.

Contact fields

Field	Description
FirstName	First name of the contact. String, up to 32 characters long.
LastName	Last name of the contact. String, to 32 characters long.
Email	Email address of the contact. String, up to 128 characters long.
PhoneWork	Work phone number of the contact. String, up to 32 characters long.
PhoneHome	Home phone number of the contact. String, up to 32 characters long.
Mobile	Mobile phone number of the contact. String, up to 32 characters long.
Employment	An Employment structure (see below) describing the this contact's current employment details.
SpecialDiet	Special diet requirements for the contact. String, up to 64 characters long.
Disability	Disability information to communicate to event organisers. String, up to 64 characters long.
Code	Code for the contact such as a membership or client number. String, up to 16 characters long.

Employment fields

Field	Description
OrganisationName	The name of the organisation for the contact. String, up to 64 characters long.
Position	The job or position of the contact within the organisation. String, up to 64 characters long.
Department	The department of the contact within the organisation. String, up to 64 characters long.
BusinessUnit	The business unit of the contact within the organisation. String, up to 64 characters long.

HTTP GET

Not supported. This resource is write-only.

HTTP POST

Creates a new registration for the associated event.

The simplest way to create a registration is with a direct HTTP POST request with a JSON body containing the registration data. This is the preferred method of using the resource. Modern web browsers that support the CORS standard can use this method.

For older web browsers with more restrictive cross-domain security, this resource supports JSONP.

JSONP invocation

JSONP works only with HTTP GET requests, and this resource supports an alternative URI format to achieve effective HTTP POSTs using a GET and JSONP.

Browsers calling this endpoint from JavaScript can append a number of parameters to execute the operation using a cross-domain HTTP GET. All parameters are required.

method=post: Configures the API to execute this request as if it were a HTTP POST
format=json: Specifies the client will receive a result payload as JSON
callback=FunctionName: Specifies the JSONP callback function name
jsonData={"Contact":{"FirstName...}: The encoded JSON data representing the equivalent POST payload

Important notes about JSONP

JSONP requests always return a HTTP 200 status (including for errors). Client script must check for a failure by testing the response object for the presence of a Success field with the value false. If present, the response will usually also contain Code and Message fields with more information about the error. This field is never present in a success response.

See the JSONP examples below for demos of success and error responses.

Because the payload for the request must be specified as part of the URI in the jsonData parameter, there are limits on the amount data that can be submitted. Browsers have differing limits on maximum URI lengths, but most limit URIs to a maximum of 1900-2100 characters. Script errors may occur if generated URI string exceeds the limit for the browser. A safe 'defacto' limit to use is 1900 characters (inclusive of URI-escape codes in parameters).

Required parameters

There are some required parameters that must be used with HTTP POSTs to this resource.

Parameter Description

region The code of the region providing context for the new registration. Usually the region represents the country where the registration is being accepted. On multi-region platforms this parameter will be used to assign regional information to new contacts and organisations.

Available values for this parameter depends on the installed regions for the platform. The region code is usually a two-letter code for the country, such as nz or au.

Parameter	Description
region	The code of the region providing context for the new registration. Usually the region represents the country where the registration is being accepted. On multi-region platforms this parameter will be used to assign regional information to new contacts and organisations. Available values for this parameter depends on the installed regions for the platform. The region code is usually a two-letter code for the country, such as `nz` or `au`.

HTTP POST Response

The resource endpoint will respond with a HTTP status code from the table below. This section is not generally applicable for JSONP requests, where the response code will always be 200.

Status	Description
200 OK	The registration was successfully created. The response will contain a JSON representation of the registration.
400 Bad Request	The URI parameters or HTTP POST body contains malformed or invalid parameters. The response will contain a JSON object with details of the error.
404 Not Found	The event specified in the URI does not exist, or is no longer available for public registration.
405 Method Not Allowed	The event does not allow registrations to be created using POST requests to this resource. This error occurs if the event requires payment or is configured to allow registrations only via a managed process (such as the website checkout).
406 Not Acceptable	The request does not contain any valid `Accept` header, or any `&format=` query value. Requests must specify the acceptable media type(s) the API can use for responses using one of these methods. Supported values for the `Accept` header: `application/json` Supported values for the `format` query parameter: `json`
409 Conflict	The response will contain a JSON object with one of these error codes: `DuplicateRegistration` - the specified individual is already registered for the event.
415 Unsupported Media Type	The request has an invalid or missing `Content-Type` header value. This header is required to indicate the media type of the HTTP POST body content. Supported values for the `Content-Type` header: `application/json`.
422 Unprocessable Entity	The request is understood but could not be processed. The response will contain a JSON object with one of these error codes: `EventFull` - the event is full and no more registration spots are available.
500 Internal Server Error	A server error has occurred while processing the request. The response will contain a JSON object with the error details.

HTTP POST Examples

Standard HTTP POST

This example creates a registration for Julie Everett from the NZ region for event with ID 987. This is a typical scenario for a direct HTTP POST to this resource.

HTTP request

POST /api/2012-02-01/pub/resources/events/987/registrations/?region=nz
Accept: application/json 
Accept-Encoding: gzip, deflate 
Content-Type: application/json 
Content-Length: 451

{
   "Contact":{
      "FirstName":"Julie",
      "LastName":"Everett",
      "Email":"julie.everett@example.org",
      "PhoneWork":"+64 4 123 4567",
      "Mobile":"+64 21 1234 5678",
      "Employment":{
         "OrganisationName":"Acme Industries Ltd",
         "Position":"General Manager",
         "Department":"Human Resources"
      }
   },
   "Comments":"Test comment"
}

HTTP response

HTTP/1.1 200 OK
Cache-Control: no-cache
Content-Type: application/json; charset=utf-8
Vary: Accept-Encoding
Date: Tue, 1 Jan 2013 00:00:00 GMT
Content-Length: 291

{
   "Contact":{
      "FirstName":"Julie",
      "LastName":"Everett",
      "Email":"julie.everett@example.org",
      "PhoneWork":"+64 4 123 4567",
      "Mobile":"+64 21 1234 5678",
      "Employment":{
         "OrganisationName":"Acme Industries Ltd",
         "Position":"General Manager",
         "Department":"Human Resources"
      }
   },
   "Comments":"Test comment"
}

JSONP POST (success result)

This example creates a registration for Julie Everett from the NZ region for event with ID 987 using a HTTP GET and JSONP parameters. The API returns a success callback response.

IMPORTANT: Ensure the jsonData parameter is properly URI encoded to ensure special characters are handled. The builtin javascript method encodeURIComponent can be used to encode strings for use in a URI. The example below does not show the parameter escaped for readability.

HTTP request

GET /api/2012-02-01/pub/resources/events/987/registrations/?method=post&format=json&region=nz&jsonData={"Contact":{"FirstName":"Julie","LastName":"Everett","Email":"julie.everett@example.org","PhoneWork":"+64 4 123 4567","Mobile":"+64 21 1234 5678","Employment":{"OrganisationName":"Acme Industries Ltd","Position":"General Manager","Department":"Human Resources"}},"Comments":"Test comment"}&callback=myRegisterCallback

HTTP response

HTTP/1.1 200 OK
Cache-Control: no-cache
Content-Type: application/javascript; charset=utf-8
Vary: Accept-Encoding
Date: Tue, 1 Jan 2013 00:00:00 GMT
Content-Length: 291

myRegisterCallback({"Contact":{"FirstName":"Julie","LastName":"Everett","Email":"julie.everett@example.org","PhoneWork":"+64 4 123 4567","Mobile":"+64 21 1234 5678","Employment":{"OrganisationName":"Acme Industries Ltd","Position":"General Manager","Department":"Human Resources"}},"Comments":"Test comment"})

JSONP POST (error result)

This example creates a registration for Julie Everett from the NZ region for event with ID 987 using a HTTP GET and JSONP parameters. The API returns an error callback response because this individual has previously registered for this event.

Error responses are denoted by the presence of a { Success: false } value in the callback response object. This parameter is omitted for successful responses.

HTTP request

GET /api/2012-02-01/pub/resources/events/987/registrations/?method=post&format=json&region=nz&jsonData="{"Contact":{"FirstName":"Julie","LastName":"Everett","Email":"julie.everett@example.org","PhoneWork":"+64 4 123 4567","Mobile":"+64 21 1234 5678","Employment":{"OrganisationName":"Acme Industries Ltd","Position":"General Manager","Department":"Human Resources"}},"Comments":"Test comment"}"&callback=myRegisterCallback

HTTP response

HTTP/1.1 200 OK
Cache-Control: no-cache
Content-Type: application/javascript; charset=utf-8
Vary: Accept-Encoding
Date: Tue, 1 Jan 2013 00:00:00 GMT
Content-Length: 291

myRegisterCallback({"Success":false,"Code":"DuplicateRegistration","Message":"Julie Everett (julie.everett@example.org) is already registered for this event"})

HTTP PUT

Not supported.

HTTP DELETE

Not supported.