Arlo

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.

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.

}