Getting Started

👍

Work in Progress

These docs are still work in progress, but we would like to provide guidance tailored to your needs as soon as you have them.
So, if you're missing any endpoint or examples - contact us via Intercom so that we could improve!

Full documentation is still available here: https://apidocs.recruitee.com/

In order to use the ATS API, a client (any application that would like to use the API) needs to authenticate first with a header Authorization: Bearer <token>

🚧

Token scope

Each user can generate an API Token that will have the exact same scope of permissions as the user - it will allow to perform the same actions as in the web or mobile application in the name of that user.

Currently it's not possible to set the access level of the API Token (e.g. with lower or higher access level) or turn off API Token generation for some roles.

Be careful when sharing your API Tokens with other people.

Generate API Token

To start, go to token settings. You can find them in Settings > Apps and plugins.

You should now see an overview of your API Tokens.

Click on "Add new token" button and provide the API Token label for easier distinguishing. Click "Save".

📘

To continue, first verify that it's you

If you're doing this for the first time, you'll be prompted to provide a password to your account. Afterwards, you will have to re-authenticate every 3 minutes.

After successful authentication, your personal API Token is created.

That long string of characters is your API Token. Only you can see your tokens, not even an account administrator can view them.

📘

Tokens and access to companies

API Tokens are generated per user and per company, with respect to their user role. This means that if you have two companies on your account, you won't be able to use the same API Token for both companies and you will not have the same list of API Tokens in all companies, when you enter the Settings.

Example:
You have 2 companies, A and B, in A you’re an administrator and in B you’re a reviewer. You create a token ABC while logged in to company A - when you log in to company B, you won't see token ABC. While logged in to company B, you create token XYZ.
Using a token ABC for action in company A will give you full power of administrator but won't allow to perform any actions for company B, whereas using XYZ for company B will allow you to perform actions which are available to reviewer role (and won't allow to perform actions for company A).

You can use the same API Token for unlimited integrations, but we advise to use a separate one for each API integration for easier management.

Using the API Token

To make your calls to API, you will also need your company ID. You can find it on the page with API Tokens.

Copy the API Token by clicking Show token and clicking on the Token.

Now you can use it in API call header like this:

curl -X GET \
  https://api.recruitee.com/c/1111/admin \
  -H 'Authorization: Bearer djh6M1ppSSt2aTlITEpBVFM2OUc4dz09'

❗️

Revoking your API Tokens

You can revoke your API Tokens anytime, but remember that any integrations using it will stop working - each request that needs authentication will then return 401 Unauthorized status.
Since it's not possible to regenerate existing API Tokens, you will have to create a new API Token and update it in your integration.

🚧

Revoking API Tokens of other users from your company

Removing a user from your company will restrict access of their API Tokens to your company. Tokens are not expired (user will still have it in their settings), but any integration built for your company using their token, will stop working due to lack of authorization.

Rate limiting

Currently we do not limit the API usage or number of generated API Tokens.

How to use this documentation

Documentation is build from three parts:

1. On the left you can find a sidebar navigation. Note, that it's divided into Careers Site API, ATS API, Guides, and Partner API.

2. In the center there is the main part of the documentation. Here you will find brief description what the endpoint is about, what arguments it takes into path, query and body. If there are more use cases, they will be described in this section with examples.

3. On the right you can find examples of API calls and example responses with their codes.

📘

Try It!

Try It button allows you to test the endpoints in the browser, from the documentation.
All you need is to provide API Token, company ID and additional fields that are required (you can fill in optionals as well, of course).
These requests are run live on your account, so be careful when modyfing data (POST, PATCH, DELETE methods)

It may not work when uploading files is involved (files, CVs, photos), because this feature doesn't support form data requests.