1. Introduction
The WorkCast API is built on HTTP. Our API is RESTful and it:
- Uses predictable, resource-oriented URLs.
- Uses built-in HTTP capabilities for passing parameters and authentication.
- Responds with standard HTTP response codes to indicate errors.
- Returns JSON.
To give you an idea of how to use the API, we have annotated our documentation with code samples.
1.1 Base URL
All registration API URLs referenced in this documentation start with a base part. For all customers, the base URLs are:
Authentication API
|
https://authapi.workcast.com/v1.0 |
Registration API
https://regapi.workcast.com/v1.0 |
1.2 Authentication
When you sign up for an account, you are given an API key. You authenticate to the WorkCast API by providing your API key in the request. As part of an upcoming WorkCast Stratus update, you will be able to manage your API key in the Integration tab under the Administration section of your login area. In the meantime, contact your account manager for more information.
Authentication to the API occurs via the OAUTH2 protocol via the following API call (see also section 1.1 Base URL – Authentication API):
POST /signin |
Body:
|
{ |
|
|
1.2.1 Example - Request
| Warning: Our examples are using the curl utility for API examples. UNIX shells require that some characters must be escaped, for example $ becomes \$. For Windows, all double quotes must be escaped so " becomes \". |
|
curl -H "Content-Type: application/json" -H "APIKey: <API Key supplied by WorkCast>" -d "" -X POST https://authapi.workcast.com/v1.0/signin |
|
{ "idToken": "eyJraWQiOiIxMUR4Smo0YTlHM0dqWU1yNnpKbWNnTGhWMHY1SFZCXC9cL3llc2pMWjV2emc9Iiw7YWxnIjoiUlMyNTYifQ.eyJzdWIiOiI5YWY0YzZhMi03MDkxLTQ4MjEtOGYxMC0xZjA1NDQ1MzRkYjYiLCJhdWQiOiJxaXYydnNpdmF0aHRlMzNoYjB0ZHVvODBuIiwiY3VzdG9tOmFjY291bnRfbnVtYmVyIjoiMTE2NTAiLCJldmVudF9pZCI6IjkyNjZkZTdhLTI1MDItNDQwMC04OWJlLWYzZjAwNmY4MWM5ZCIsInRva2VuX3VzZSI6ImlkIiwiYXV0aF90aW1lIjoxNTY3NjAwOTczLCJpc3MiOiJodHRwczpcL1wvY29nbml0by1pZHAuZXUtd2VzdC0xLmFtYXpvbmF3cy5jb21cL2V1LXdlc3QtMV82NFlJOWlIcksiLCJjb2duaXRvOnVzZXJuYW1lIjoibWFyay5yYWluc2ZvcmQub3RlIiwiZXhwIjoxNTY3NjA0NTczLCJpYXQiOjE1Njc2MDA5NzN9.hIJPX4TxU7GV90JjCyHOdO6iUkt7o8NQQWxeslw4wl_Ox0IcUlLiXFSNGFZx75ly0MC8N1WI8krrPPrDRbyDATVb5_YZ-5ssR3nqZyh-y0e917OSqZvtTUfCqdN_FyCgtqa9W2eyF22BQjX1o1xHto6Jbc7VPGVgle11PRzGCYbABM2co9eGRUE9rJh4c5LSBFZFsBIR0wb2xbcfwPGXW9mEukqIL1v1Ca0bFamKeRE5uNrPJzuyLnmq62tg3jgDdKwBJ1NKC_ROCuGXX9ASFZ1QoCUpd5C1-erOaWarziooyjliQtj4tiH8XM0Gn-c6RvSrZVAUZAW98GjKBHhZPw", "expiresIn": 3600, "paging": null, "responseCode": 200, "message": "Ok" } |
NOTE: The JWT bearer token must be used in all subsequent API calls after authentication. Tokens expire periodically and will result in a 401 response (see section 1.3 below). Tokens must be refreshed at this point via a new “signin”.
1.3 HTTP Response Codes
WorkCast returns standard HTTP response codes.
|
Code |
Description |
|
200 |
The request has succeeded |
|
400 |
Bad Request |
|
401 |
Unauthorised - Invalid API key provided |
|
402 |
Request Failed - Parameters were valid but request failed |
|
404 |
Not Found - The requested item does not exist |
|
405 |
Method not allowed |
|
429 |
Too Many Requests – API limit exceeded |
|
500, 502, 503, 504 |
Server Errors - something is wrong on WorkCast’s end |
2. Domains
The following data domains are exposed via the API:
- Register
- Register Status
Note that all endpoints listed in this section use the Registration API Base URL as defined in section 1.1.
2.1 Register
The API allows you to post-registration data programmatically.
2.1.1 Standard Parameters
Standard parameters appear only once per registration.
|
Parameter |
Description |
Type |
Max Size |
Required? |
|
eventPak/channelPak |
Event or channel public access key (depending upon whether an event or channel is being registered against) |
Character |
16 |
Yes |
|
sessionPak |
Session public access key – one for each session being registered against |
Character |
16 |
Yes |
|
|
Email address |
Character |
100 |
Yes |
|
title |
Title/Salutation |
Character |
20 |
|
|
firstName |
First Name/Forename |
Character |
50 |
|
|
lastName |
Last Name |
Character |
20 |
|
|
company |
Company Name |
Character |
50 |
|
|
jobTitle |
Job Title |
Character |
50 |
|
|
addressLine1 |
Address Line 1 |
Character |
30 |
|
|
addressLine2 |
Address Line 2 |
Character |
30 |
|
|
addressLine3 |
Address Line 3 |
Character |
30 |
|
|
city |
City |
Character |
20 |
|
|
countyOrState |
County or State |
Character |
20 |
|
|
postCode |
Post/Zip Code |
Character |
20 |
|
|
countryCode |
Country Code |
Character |
5 |
|
|
phone |
Phone Number |
Character |
20 |
2.1.2 Custom Parameters
Multiple custom data items (no more than 20) can be submitted per registration.
|
Parameter |
Description |
Type |
Max Size |
Required? |
|
itemDesc |
Data Item Description |
Character |
200 |
|
|
itemValue |
Data Item Value |
Character |
500 |
PUT /register |
Create an event registration. See the examples below.
2.1.1 Examples
Event registration
| Warning: Our examples are using the curl utility for API examples. UNIX shells require that some characters must be escaped, for example $ becomes \$. For Windows, all double quotes must be escaped so " becomes \". |
Request:
curl -H "Authorization: Bearer " -H "Content-Type: application/json" -X PUT -d "" https://regapi.workcast.com/v1.0/register |
Body:
"registration": { "event": { "eventPak": "1234567890123456", "sessions": [ {"sessionPak": "1234567890123456"}, {"sessionPak": "2345678901234561"}, {"sessionPak": "3456789012345612"} ] }, "contact": { "title": "Mr", "firstName": "Example name", "lastName": "Example name", "email": "example@workcast.com", "phone": "", "jobTitle": "Developer", "company": "WorkCast", "addressLine1": "", "addressLine2": "", "addressLine3": "", "city": "", "countyOrState": "", "postCode": "", "countryCode": "UK", "contactCustomItems": [ { "itemDesc": "Contact Preference", "itemValue": "email" }, { "itemDesc": "Send Monthly Newsletter", "itemValue": "true" } ] } } |
Response
{ "registration": { "contact": { "email": "example@workcast.com" }, "sessions": [ { "sessionPak": "1234567890123456", "queueId": 1, "status": "queued" }, { "sessionPak": "2345678901234561", "queueId": 2, "status": "queued" }, { "sessionPak": "3456789012345612", "queueId": 3, "status": "queued" } ] }, "paging": null, "responseCode": 200, "message": “ok” } |
Channel registration
| Warning: Our examples are using the curl utility for API examples. UNIX shells require that some characters must be escaped, for example $ becomes \$. For Windows, all double quotes must be escaped so " becomes \". |
curl -H "Authorization: Bearer " -H "Content-Type: application/json" -X PUT -d "" https://regapi.workcast.com/v1.0/register |
Body:
"registration": { "channel": { "channelPak": "1234567890123456", "sessions": [ {"sessionPak": "1234567890123456"}, {"sessionPak": "2345678901234561"}, {"sessionPak": "3456789012345612"} ] }, "contact": { "title": "Mr", "firstName": "Example name", "lastName": "Example name", "email": "example@workcast.com", "phone": "", "jobTitle": "Developer", "company": "WorkCast", "addressLine1": "", "addressLine2": "", "addressLine3": "", "city": "", "countyOrState": "", "postCode": "", "countryCode": "UK", "contactCustomItems": [ { "itemDesc": "Contact Preference", "itemValue": "email" }, { "itemDesc": "Send Monthly Newsletter", "itemValue": "true" } ] } }
|
Response
{ "registration": { "contact": { "email": "example@workcast.com" }, "sessions": [ { "sessionPak": "1234567890123456", "queueId": 1, "status": "queued" }, { "sessionPak": "2345678901234561", "queueId": 2, "status": "queued" }, { "sessionPak": "3456789012345612", "queueId": 3, "status": "queued" } ] }, "responseCode": 200, "message": “ok” } |
2.2 Register Status
Check the status of a registration request.
|
Parameter |
Description |
Type |
Max Value |
Required? |
|
limit |
Maximum number of records to return (default 25) |
Integer |
100 |
No |
|
queueId |
Queue id(s) to check |
Integer |
2147483647 |
Yes |
GET /registerstatus |
Submit a registration status request. See example below.
2.2.1 Example
Submit a registration status request.
| Warning: Our examples are using the curl utility for API examples. UNIX shells require that some characters must be escaped, for example $ becomes \$. For Windows, all double quotes must be escaped so " becomes \". |
curl -H "Authorization: Bearer " -H "Content-Type: application/json" -X GET -d "" https://regapi.workcast.com/v1.0/registerstatus |
Body:
{ "limit": 10, "checks": [ { "QueueId": 1 }, { "QueueId": 2 }, { "QueueId": 3 } ] } |
Response
{ "totalCount": 3, "checkResults": [ { "queueId": 1, "status": "success", "sessionPak": "1234567890123456", "email": "example@workcast.com", "contactId": 4566 }, { "queueId": 2, "status": "success", "sessionPak": "2345678901234561", "email": "example@workcast.com", "contactId": 4566 }, { "queueId": 3, "status": "queued", "sessionPak": "3456789012345612", "email": "example@workcast.com", "contactId": 0 } ], "paging": null, "responseCode": 200, "message": “ok” } |
3. Limits
WorkCast imposes a rate limit per API endpoint. Users may issue no more than 100 requests per minute, per account.
If you exceed your rate limit, you will receive an HTTP 429 response (See section 1.3 Error Response Codes) and must wait 60 seconds before submitting more requests.