The WorkCast API is built on HTTP. Our API is RESTful and it:
To give you an idea of how to use the API, we have annotated our documentation with code samples.
All registration API URLs referenced in this documentation start with a base part. For all customers the base URL’s are:
Authentication API
|
https://authapi.workcast.com/v1.0 |
Registration API
https://regapi.workcast.com/v1.0 |
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:
|
{ |
|
|
| 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: test_api_key" -d "" -X POST https://authapi.workcast.com/v1.0/signin |
Response – JWT Bearer Token
|
{ "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”.
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 |
The following data domains are exposed via the API:
Note that all endpoints listed in this section use the Registration API Base URL as defined in section 1.1.
The API allows you to post registration data programmatically.
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 |
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 examples below.
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” } |
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.
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” } |
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.
Lorem ipsum dolor sit amet, consectetur adipiscing elit
You may also be interested in:
Call: +1 206 259 2141
600 1st Ave, Suite 541-543, Washington, 98104, United States
Call: +44 (0)844 870 4912
Chase House, 4 Mandarin Road, Rainton Bridge Business Park, Sunderland, DH4 5RA, UK
Call: +44 (0)844 870 4912
Great Michael House, 14 Links Pl, Edinburgh, EH6 7EZ
Copyright © 2019 WorkCast Corporation. All Rights Reserved.
