Using our API requires prior knowledge/experience in APIs and how to work with one. This article explains what the Teamtailor API is and how to get started.
What is the Teamtailor API and what does it do?
Our Teamtailor open API follows the JSON API Specification and it can be used to import, edit, and export information from/to one's Teamtailor account. This could be anything from fetching a list of jobs, updating a job, updating a user - even creating a user.
Teamtailor provides two regions for data processing and storage: EU (Ireland) and US West (Oregon). The API URL you use in your API calls will depend on the region where your account is stored.
EU Region: api.teamtailor.com
US West Region: api.na.teamtailor.com
Getting started
To be able to use our API an API key needs to be generated in Settings → Integrations → API keys on your Teamtailor account. Note that this page is only accessible for users with Company Admin access.
Here you can both create new keys and delete existing ones. Note that once a API key is created it cannot be edited, only deleted.
To create an API key click + New API Key at the top right corner.
There are three different types of keys, with different permissions and scopes. These are all explained in our documentation here, and are as follows:
Permissions:
Public - access all public data available on the career site
Internal - public + internal data (for eg. unlisted/internal jobs, departments, locations)
Admin - access to everything in an account
Types:
Read - only fetch information and ‘read’ it
Write - only create new information
Read/Write - can do both
Use case example
If eg. fetching a list of jobs via our AP and you only want to fetch a list of published jobs, it's good to use a Public Read key as that gives you access to public data on the career site, like published jobs. Should you instead wish to be able to fetch a list of all locations, public or not - you'd need to have a key with at least Internal Read permissions.
Some data is very restricted due to security reasons (eg. candidates' information/data) and can only be accessed using a key with an Admin scope/permission. If that's the case, this is always stated in the API documentation.
Support
With all available endpoints in our documentation, everything that is required for an action should be included in the documentation with examples that can be tested if needed.
Should you have any general questions about the API documentation, feel free to reach out to our support at support@teamtailor.com but please note that we don’t offer API implementation support.
If something is not listed in the documentation it is most likely not available for implementation. Custom scripts or further integrations can be combined with the requests available in our public API scripts, however, how to go about it is entirely up to the customer.