API Registration Documentation

Last updated September 4, 2019

 

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 URL’s 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:

{
    "apiKey": "<API Key>"
}

 


Warning: Keep your API key secret!

 

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: 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”.

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

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 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.

Additional Articles

You may also be interested in: