The Staffjoy API controls access to all data within the application. Staffjoy's applications use this API for all functionality, and we invite developers to build their own API integrations with our system.
The Staffjoy API uses REST, and data is encoded in JSON. Resources are logically structured, and IDs are integers.
Our team supports developers using our API. Please email us at [email protected] with any questions. We can help with design questions, debugging, and setting up sandbox accounts.
Mailing List
If you develop on the Staffjoy API, please join the Staffjoy API Mailing List for important news about changes or deprecations.
Envelope
GET endpoints return information in an envelope with the key "data". This allows us to package metadata in certain circumstances with responses, such as pagination.
Allowed Methods
The Staffjoy API uses standard GET, POST, PATCH, and DELETE methods to modify endpoints. Note that we support PATCH in favor of PUT.
Errors
Staffjoy uses standard HTTP status codes to communicate errors. The response body is JSON-encoded, and may include a "message" key with further information about the failure.
Common codes used by our API include:
| HTTP Status Code | Status |
|---|---|
| 200 - OK | API call successful |
| 201 - Created | The resource was created |
| 204 - Success No Content | The request succeeded and there is no response data. Often used for DELETE endpoints. |
| 400 - Bad Request | The request failed, likely due to invalid or missing parameters. Check for a "message" value in the response with further details. |
| 401 - Unauthorized | The API key did not have permission to complete this action. In some cases, an alternative endpoint may exist for security purposes - please contact support if you have questions. |
| 404 - Not Found | The resource does not exist |
| 429 - Too Many Request | The API Key was rate-limited due to too many requests. See below for rate limit information. |
| 500- Server Error | Staffjoy's API encountered an unexpected error. Please email support for help |
| 502, 503 - Service Error | Staffjoy's API encountered an intermittent error -please try again. |
Client Libraries
Staffjoy currently has one official client library in Python. Learn more on Github or install it via pip install staffjoy.
Datetime Handling
All datetime objects in Staffjoy use ISO 8601 formatting. For datetime objects without a specified offset, [UTC (Coordinated Universal Time)])https://en.wikipedia.org/wiki/Coordinated_Universal_Time) is assumed.
Rate Limiting
Staffjoy's API limits each IP address and each API key to 300 requests per minute*. Exceeding this limit will result in a 429 - Too Many Requests error. If you require a higher limit, please contact support.
Pagination
For some group endpoints, we use a limit and offset variables to handle pagination. Lists are sorted by ID, ascending. The limit controls how many items are returned, and the offset specifies the beginning of the search window.
So, to search a 75-item list, you may query an endpoint 3 times, each with limit of 25, and with offset of 0, 25, and 50.