Note
The examples in this document use curl and the REST API directly.
If you are using .NET, take a look at our .NET SDK.
If you are using PHP, take a look at our example PHP scripts.
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/
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/testResponses
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 program. Contact your 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 OKNote
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 program.
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/testand 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=429HR Data Sync (Employee)
Note
Your XML file must be attached (i.e. using a multipart form method) rather than included in the body of the request.
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 relevant administrators.
Below is a curl example:
curl -u api-key:6wiIBWbGkBMo1mRDMuVwkw1EPsNkeUj95PIz2akv --form "file=@employees01052018110314.xml" https://yourcompany.workstars.com/admin/api/v2/hrdatasync/employeeTo 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.xsdHR Data Sync (Position)
Note
Your XML file must be attached (i.e. using a multipart form method) rather than included in the body of the request.
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/positionTo 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
Comments
0 comments