REST API v2

This is the documentation for accessing the Workstars REST API. When documenting a resource, we use curly braces for identifiers. For example {subdomain} when talking about the URL for your account, i.e. https://{subdomain}.workstars.com/admin/api/v2/

Note

The examples in this document use curl and the REST API directly. If you are using .NET we recommend you install and use our .NET SDK instead, for further information and code examples please see the “.NET SDK” documentation

Security and Authentication

  • This is an SSL only API and you must have an API key from an active account to make API requests.
  • To create/view/change your key go to your admin portal (i.e. https://{subdomain}.workstars.com/admin) select Settings then API.
  • Authentication to the API occurs via HTTP Basic Auth (see http://en.wikipedia.org/wiki/Basic_access_authentication).
  • Use ‘api-key’ as the user name and your API key as the password e.g. api-key:6wiIBWbGkBMo1mRDMuVwkw1EPsNkeUj95PIz2akv

Warning

Keep your API key secret as anyone who has it can access your data. If you think it might be compromised or you want to rotate it regularly you can generate a new one from within the admin portal.

Below is an example using curl:

curl -u api-key:6wiIBWbGkBMo1mRDMuVwkw1EPsNkeUj95PIz2akv https://yourcompany.workstars.com/admin/api/v2/test

Responses

All responses will always include the appropriate HTTP status code - see below.

Please note that all attributes of a method response are not always present, you should never assume that a certain attribute is present.

The responses use JSON-encoding. See http://en.wikipedia.org/wiki/Json for more information

Status Code Description
200 OK Everything worked as expected
400 Bad Request Often this is because a required parameter is missing. Error message field should indicate which one and why.
401 Unauthorized This is normally due to an incorrect sub-domain or invalid API key
403 Forbidden You are trying to access an endpoint that is not configured for your scheme. Contact you account manager for further assistance.
404 Not Found The path cannot be found, check the URL and parameters
409 Conflict This is usually because there is already a file queued for processing, wait till that has completed.
413 Request Entity Too Large The request is larger than the server is willing or able to process, check the size of any posted files.
429 Too Many Request Your script is making too many requests and is being rate limited.
500 Internal Server Error Something went wrong at our end. If problems persist please contact your account manager.
503 Service Unavailable The API is temporarily unavailable, this is probably for maintenance.

Success

Successful requests are responded with status codes in the 200 range.

Depending on which API you are calling and the action performed you may receive just a success status code in the header or a success status code and a JSON-encoded response.

HTTP/1.1 200 OK

Note

When posting a file a status code of 200 does not mean the file was processed, it just means it has been received.

Business Errors

Unsuccessful requests are responded with HTTP status codes in the 400 range.

All responses are sent JSON-encoded in the following format and will include an error message describing the problem.

HTTP/1.1 401 Unauthorized
{
    "error" : "Couldn't authenticate you, check your subdomain and API key are correct."
}

Please check http://status.workstars.com for the current status of the platform.

API Endpoints

All API’s described below should be appended onto the end of your platform URL https://{subdomain}.workstars.com, this is the URL used to access your scheme.

Test

GET /admin/api/v2/test

This is a simple test endpoint to verify you can connect with the correct credentials.

Below is a curl example:

curl -u api-key:6wiIBWbGkBMo1mRDMuVwkw1EPsNkeUj95PIz2akv https://yourcompany.workstars.com/admin/api/v2/test

and the expected response:

HTTP/1.1 200 OK
{
    "message" : "Hello World"
}

this API also accepts a parameter to trigger each of our error codes for testing:

curl -u api-key:6wiIBWbGkBMo1mRDMuVwkw1EPsNkeUj95PIz2akv https://yourcompany.workstars.com/admin/api/v2/test?statuscode=429

HR Data Sync (Employee)

Note

This POST requires files to be submitted and does not work if you send the file contents in the body. This is because they must be correctly encoded and hence you should use a multipart form method.

POST /admin/api/v2/hrdatasync/employee

This endpoint is used to upload your employee file to our HR Data Sync process. Uploaded files will be validated within a few minutes and any validation issues will generate a notification to relevent administrators.

Below is a curl example:

curl -u api-key:6wiIBWbGkBMo1mRDMuVwkw1EPsNkeUj95PIz2akv --form "file=@employees01052018110314.xml" https://yourcompany.workstars.com/admin/api/v2/hrdatasync/employee

To retrieve the current XML schema for the employee file use:

GET /admin/api/v2/hrdatasync/employees.xsd

You should use this to validate your file locally before posting.

Below is a curl example:

curl -u api-key:6wiIBWbGkBMo1mRDMuVwkw1EPsNkeUj95PIz2akv https://yourcompany.workstars.com/admin/api/v2/hrdatasync/employees.xsd

HR Data Sync (Position)

Note

This POST requires files to be submitted and does not work if you send the file contents in the body. This is because they must be correctly encoded and hence you should use a multipart form method.

POST /admin/api/v2/hrdatasync/position

This endpoint is used to upload your position file to our HR Data Sync process. Uploaded files will be validated within a few minutes and any validation issues will generate a notification to relevent administrators.

Below is a curl example:

curl -u api-key:6wiIBWbGkBMo1mRDMuVwkw1EPsNkeUj95PIz2akv --form "file=@positions01052018110545.xml" https://yourcompany.workstars.com/admin/api/v2/hrdatasync/position

To retrieve the current XML schema for the position file use:

GET /admin/api/v2/hrdatasync/positions.xsd

You should use this to validate your file locally before posting.

Below is a curl example:

curl -u api-key:6wiIBWbGkBMo1mRDMuVwkw1EPsNkeUj95PIz2akv https://yourcompany.workstars.com/admin/api/v2/hrdatasync/positions.xsd