An API (Application Programming Interface) allows different systems to communicate and exchange data.

Our Teamtailor API follows the JSON:API specification and lets you retrieve, create, and update information in your Teamtailor account. For example, you can fetch a list of jobs, update a job, or create and update users.

Using the API requires prior knowledge of APIs and how to work with them. This article explains how the Teamtailor API works and how to get started.

To access our API, you need to have an API key from your Teamtailor account. Under Settings → Integrations → API keys, you can create a key by clicking + New API Key in the top-right corner.

Once a key is created, its API scope and permissions cannot be changed. You can edit its name and description, and update its expiry date.

You can find more information about permissions and access types in our API documentation.

You can manage your API keys under Settings → Integrations → API keys. Here, you can view key details, edit existing keys, check their status, and manage their expiration.

Each key displays its name, description, creation date, creator, and last-used information where available. This helps you identify what each key is used for and who is responsible for it.

For security, API keys are masked by default. Click Show to reveal the full key, or Copy to copy it.

New API keys start with tt_api_. Public widget keys used in your career site's HTML start with tt_pub_.

Each API key must have a unique name within your company. Names are case-insensitive, so you cannot create two keys named Integration and integration. The names Widget and bi-connector are reserved for keys managed by Teamtailor.

To update an existing key, click Edit. You can change its name and description, but its permissions and access type cannot be changed after creation.

Keys that haven't been used for 90 days are marked Inactive to help you identify keys that may no longer be needed. Keys created by Teamtailor are marked Managed by Teamtailor.

The Expires column shows each key's expiration date and status:

An expired key can no longer authenticate API requests. Any integration still using it will receive the same error as it would with an invalid key.

Reminder emails are sent to the person who created the key 14 days and 1 day before it expires. If the creator can no longer log in, the reminders are sent to the account's admins instead.

Expired keys remain in the list until you delete them.

For older keys created before usage tracking was introduced, keys that have never been used display Not used since May 21, 2026.

If you need to replace a key, you can click Rotate to create a new one while giving your integration time to switch over.

When rotating a key, you can choose when the old key stops working:

The new key keeps the same name, description, and permissions as the original key. The old key is marked (replaced) after its name and continues working until the selected date. This gives you time to update your integration to use the new key.

Check the Last used column to see whether your integration is still using the old key. Once you've switched to the new key, you can delete the old one.

The Rotate option isn't available for keys managed by Teamtailor, expired keys, or keys that have already been replaced.

You can delete keys that are no longer needed. Before confirming deletion, you'll see details about the key, including its name, description, masked value, permissions, creator, and last-used information where available.

If the key has been used within the last 30 days, you'll see a warning that an integration may still depend on it. For Widget keys, the warning indicates that the widgets may still be in use on your career site.

Review these details before deleting a key, as removing one that's still in use can interrupt an integration.

If you are, for eg, fetching a list of jobs via our API 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., candidate 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.

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.