API Reference

The JobScore Hire API v2 is a RESTful API designed to have predictable, resource-oriented URLs.

We use built-in HTTP features, like HTTP authentication and HTTP verbs, which can be understood by off-the-shelf HTTP clients. We use HTTP response codes to indicate API errors.

• JSON will be returned in all responses from the API, including errors.

• Lists default to created_on descending unless stated otherwise (jobs default to title ascending). Use sort and order (asc/desc) where documented.

• We reserve the right to add more properties to objects, but will never change or remove them.

• All strings must be UTF-8 encoded.

• Dates are encoded as strings in the YYYY-MM-DD format.

• Timestamps are encoded using the ISO 8601 convention.

• All objects have an immutable 22 character unique identifier (uid) and immutable created_on and updated_on timestamps.

• All dates and timestamps are UTC and encoded in ISO 8601 format (e.g. 1969-10-05, 2024-12-24T23:59:59Z). Timestamp inputs with an explicit offset are converted to UTC; inputs without one are assumed UTC.

If you want to report a bug, request a feature or ask a question about the JobScore Hire API & Webhooks, please go to this GitHub repository and open an issue.

Usage

The JobScore Hire API lets you build a variety of applications and integrations. However, the JobScore Hire API is not designed for you to build a customized careers site / jobs page. Please build your careers site using the Job Feed API.

Version 2 adds a number of PATCH and POST endpoints for create and update use cases, and is not backwards compatible with v1, which is deprecated.

The JobScore Hire API is available to Enterprise customers and select partners. Interested partners should contact [email protected].

Authentication

You authenticate to our API by providing your Personal Access Token in the request. Your tokens carry many privileges, so be sure to keep them secret and secure!

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. You must authenticate for all requests.

You can generate an access token on the Integrations > JobScore API & Webhooks page.

HTTP Token Authentication

You can authenticate via HTTP Token Authentication by sending an Authorization header with the Token parameter.

curl https://api.jobscore.com/v2/users/me \
  -H "Authorization: Token token={your_token}"

Impersonation

You can impersonate a different user by sending the X-On-Behalf-Of header. Only tokens with the Account access level can use this feature.

The content for the header must be a user’s unique identifier, which you can fetch using the List Users endpoint.

curl https://api.jobscore.com/v2/users/me \
     -H 'Authorization: Token token={your_token}' \
     -H "Content-Type: application/json" \
     -H "X-On-Behalf-Of: {user_id}"

Rate Limits

We rate limit by token. By default, we allow 3,600 requests/hour for GET requests and 400 requests/hour for POST/PATCH/DELETE requests. On every request, the HTTP headers RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset will be returned. POST/PATCH/DELETE requests also have burst protection, meaning that you can perform up to 20 requests/minute. If you exceed this limit, you will receive a 429 Too Many Requests response with the corresponding code. We use a fixed window implementation, meaning that your number of requests will be reset at the top of the next clock hour. A 429 response carries a Retry-After header in seconds.

curl https://api.jobscore.com/v2/users/me \
     -H "Authorization: Token token={your_token}" \
     -v

# Among other headers, you will find the following ones:
(...)
< Ratelimit-Limit: 3600
< Ratelimit-Remaining: 2891
< RateLimit-Reset: 1683576000
(...)

Required HTTP Headers

The Content-Type header must be set on every POST or PATCH. The Accept header is not required, but is recommended.

Responses and Errors

We use HTTP response codes to indicate success or failure of a request.

Response codes in the range 2xx indicate a successful request; 4xx range indicates an error with your request (this could be an invalid Content-Type, missing or invalid parameters, etc), and 5xx range indicates an error on our servers.