Staffjoy Suite API Basics

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.