Teamtailor API: access, rate limits, webhooks, and how it compares

This is a consolidated reference for the Teamtailor API: key scopes, authentication, the JSON:API format, the documented rate limit, webhook options, and Partner API gating, with a comparison to the 100Hires API at the end.

It is written for developers and ops people at Teamtailor customers, and for HR-tech builders sizing up ATS APIs.

The Teamtailor facts below come from its documentation at docs.teamtailor.com, support.teamtailor.com, and partner.teamtailor.com, and from public repositories, with community examples labeled as such.

Teamtailor API quick reference

The facts you need before your first request, in one table.

The sections below unpack each row, plus the webhook and partner integration options the table cannot capture.

API keys and scopes

A Company Admin creates keys under Settings > Integrations > API keys. Regular users never see this page, so plan key management around your admin seats.

Each key gets a scope and an access level at creation time. Teamtailor's support article on API usage lays out the matrix:

Candidate data sits behind the Admin scope. Teamtailor restricts it deliberately for security reasons, so a Public or Internal key will not return applicant records.

Pick the smallest scope that does the job. A career-site widget that lists open roles runs fine on a Public read key; a two-way candidate sync needs Admin.

Match the base URL to your account's data-residency region - Teamtailor documents separate regional hosts tied to where the account's data lives.

Two documented facts to plan around. First, a key cannot be edited after creation: to change its scope you delete it and create a new one.

Second, Teamtailor states plainly that it does not offer API implementation support, and that anything absent from the docs is most likely not available.

There is one documented exception: for API-based data migrations, Teamtailor's Self-Import guide says support will explain the process and help with errors. General integration builds stay on you; migration questions get help.

One more access note: the docs gate the API by role and scope. They state no plan-tier requirement, so treat third-party claims of enterprise-only API access with caution.

Authentication and versioning

Auth is a static API key in a custom Token scheme. No OAuth flow, no token refresh, no expiry handling - for internal scripts that is one less moving part than OAuth-based ATS APIs.

The flip side of static keys: the docs describe no per-user consent flow and no expiry or refresh mechanism, so treat each key like a password. Create one key per integration, store it in a secrets manager, and rotate by deleting and recreating on a schedule you control.

A minimal first request looks like this:

curl "https://api.teamtailor.com/v1/candidates" \
  -H "Authorization: Token token=YOUR_API_KEY" \
  -H "X-Api-Version: 20240904" \
  -H "Content-Type: application/vnd.api+json"

The X-Api-Version header

Teamtailor versions its API with a date-stamped header, and the header is required on every request. The current public version is 20240904; a changelog note from October 2025 made the requirement explicit.

Version strings pinned in public tutorials range from 20210218 to 20240404, which tells you something useful: integrations pin a date and run on it for years. Even Make.com's no-code module asks users to go find the version string in the docs during setup.

Put the header in your HTTP client's defaults on day one. Forgetting it on one call is the classic silent inconsistency between environments.

JSON:API format and pagination

The Teamtailor API follows the JSON:API specification. Requests and responses use the application/vnd.api+json content type and wrap everything in a data envelope:

{
  "data": {
    "type": "candidates",
    "attributes": {
      "first-name": "Ada",
      "last-name": "Lovelace",
      "email": "ada@example.com"
    }
  }
}

Note the hyphens. Attribute and link keys are kebab-case (careersite-job-apply-url, not careersite_job_apply_url).

Naive JavaScript dot-access on these keys returns undefined without an error - one public Gatsby plugin issue documents exactly this trap. Use bracket notation or map keys at your API boundary.

The format pays off with related data. JSON:API's include parameter lets one request pull a job application together with its candidate and job, which cuts round trips against the rate limit - a real advantage once you internalize the envelope.

Sparse fieldsets are part of the JSON:API spec, but none of Teamtailor's roughly 129 official request examples show them, so their support is unverified.

Pagination is cursor-style: page[size] (default 10, max 30) with page[after] and page[before] cursors. Responses carry meta.record-count, meta.page-count, and first/last/prev/next links.

The payoff of JSON:API is consistency across every resource; the tax is verbose envelopes and the hyphen convention.

Rate limits and large datasets

The documented rate limit is 50 requests per 10 seconds per bucket. Exceed it and you get HTTP 429, with X-Rate-Limit-Limit, X-Rate-Limit-Remaining, and X-Rate-Limit-Reset headers to steer your backoff.

Worth saying twice: the limit is published. Some third-party guides say no numeric limit exists; Teamtailor's own API reference states the figure plainly. Trust the primary source.

There is a documented failure mode beyond 429: large unfiltered pulls from the answers and actions endpoints can return HTTP 500. The docs tell you to filter, paginate, and batch instead of requesting everything at once.

Real integrations budget for the 10-second bucket:

• Teamtailor's own sample app includes Redis-tracked rate-limit state, up to 3 retries on limit errors, and 1-hour response caching - a clear signal of the traffic patterns the API expects
• An n8n builder syncing 1,400+ candidates added an explicit wait node against the rate limit and hand-rolled pagination when payloads outgrew the HTTP node's built-in paging
• Teamtailor's Self-Import guide recommends spacing requests about 300 ms apart for bulk imports

A 429 is not an error to log and drop. Read X-Rate-Limit-Reset, sleep until the bucket refills, and replay the request. Bake that into your HTTP client once and every script you write afterward inherits correct behavior.

The practical defaults: cache reads, make writes idempotent, and treat the bucket as a design constraint rather than an edge case.

Endpoints and resources

The official reference documents 45 top-level resources across roughly 129 request examples.

The core objects a recruiting integration touches are all present: candidates, jobs, job applications, stages, notes, interviews, requisitions, custom fields, triggers, users, teams, todos, and uploads.

Write coverage varies by resource, and the differences matter for sync design:

Two specifics worth a developer's time. File uploads are a two-step flow: post a transient upload, receive a one-time URI valid for about a minute, then attach it. And candidate creation supports merge: true to dedupe by email plus a sourced: true flag for candidates without one.

The missing deletes on candidates and jobs shape sync design more than they first appear. An integration that mirrors records into Teamtailor cannot clean up after itself over the API, so plan for archive flags or manual cleanup instead of true deletion.

The same API powers Teamtailor's documented free Self-Import migration pattern, covered in the comparison section below.

Company webhooks and Partner API webhooks

Teamtailor runs two separate webhook systems, and mixing them up causes real design mistakes.

Company webhooks

Company Webhooks are the customer-facing option. A Company Admin activates the feature in the Add-on feature center, then configures endpoints in the UI. The public API exposes no webhook endpoints at all - you cannot create, list, or delete webhooks programmatically.

Events follow resource.action naming across candidates, jobs, and job applications, including field-level update triggers.

Deliveries are signed with a TT-Signature header: v1 (deprecated) signs only the resource ID, v2 signs a timestamp plus the raw request body with HMAC-SHA256. Verify against the raw body, not re-serialized JSON.

On retries, Teamtailor's own documentation disagrees with itself. The support article says failed deliveries retry 3 times.

The dedicated developer reference for the same feature says there is no retry mechanism, per a March 2026 changelog entry - and its own delivery guidance further down still tells you to prepare for retries.

The safe engineering posture: build idempotent handlers and reconcile with periodic polling, so your integration is correct under either behavior.

Check event coverage against your needs too. Event lists vary by resource, and one integration partner has publicly noted that tag changes did not reach its system - verify the events you depend on against a test account before committing.

Partner API webhooks

The Partner API offers fully programmatic webhooks - gated behind Teamtailor's Tech Partner program. Here the retry story is settled: partner webhooks do not retry failed deliveries. Signed file-upload URLs in webhook payloads stay valid for 60 seconds.

Partner API, Job Board API, and other integration surfaces

What reads as one API is really a seven-item integration map:

1. Customer JSON:API - the self-serve surface this guide covers
2. Company Webhooks - UI-configured Add-on, no API management
3. Partner API - Tech-Partner-gated, frozen at version 20180828 since 2018
4. Job Board API - beta, partner-gated: config and webhook endpoints the board implements, an XML feed regenerated 3 times a day, and JSON:API promotion resources
5. Direct Apply - lets candidates apply on a job board through inquiry and apply endpoints, with HMAC or IP-whitelist auth; Teamtailor itself recommends redirecting candidates to career sites instead
6. Public RSS jobs feed - per-company, free, no token needed
7. Self-Import - a documented usage pattern of the customer API for migrations, not a separate API

Partner access follows a fixed path: apply through the Tech Partner form, receive a sandbox, meet marketplace listing requirements, pass launch review.

Plan for partnership-dependent timelines: Pipedream's public integration request opened in March 2025, closed as a duplicate that December, and its successor issue remains open as of publication.

The Job Board API inverts the usual direction: your board implements config and webhook endpoints that Teamtailor calls when jobs are created, updated, or removed, signed with a timestamped HMAC header.

The always-included XML feed is the low-effort path; the premium feed and promotion resources come with the partnership.

If all you need is read-only job listings, skip auth entirely: one job-aggregator developer documented choosing the free RSS feed over the token-gated API for exactly that use.

What to plan for before you build

A note on evidence first: across Reddit, X, LinkedIn, podcasts, Stack Overflow, and Hacker News we found almost no developer complaints about this API. What follows is documented characteristics, not a complaint list.

• No webhook management endpoints in the public API - webhook setup stays manual
• Keys are immutable - scope changes mean delete and recreate
• No implementation support for custom integrations (migrations excepted, per the Self-Import guide)
• Required dated version header on every request
• Page size caps at 30 - sync-heavy work means many pages
• Kebab-case JSON:API keys - map them at your boundary
• Retry documentation conflict on Company Webhooks - design for at-most-once
• Check SDK fit - the official Ruby gem only gained explicit 429 handling in September 2025, and a 2021 error-handling issue in it remains open

There are positives too, judged against the same evidence standard. Static token auth is genuinely simple.

A self-described first-time API builder created a working Webflow-to-Teamtailor bridge in under 10 hours. An open-source community MCP server exists. And the RSS feed covers read-only listing needs with zero setup.

How the 100Hires API compares

100Hires is an AI-screening-focused ATS with a developer platform built around a published spec. Its 100Hires REST API (v2) makes different trade-offs on the same dimensions, so a side-by-side is the fastest way to see them.

Read the rate-limit row honestly: Teamtailor's raw ceiling is higher. The 100Hires default is a sustained-throughput allowance for new keys, lifted on request with a use case.

On access: API keys are self-serve on every plan including the free trial; company verification gates activation, and some field visibility and capabilities are plan-dependent.

A few behavioral details from the 100Hires spec worth knowing before you code. Write endpoints require a JSON content type and reject form-encoded bodies with a 415.

Batch endpoints move up to 100 records per call for messages, moves, rejections, and tags. And its 429 guidance is explicit: do not retry immediately, since repeated 429s can extend the cooldown.

Both vendors document API migration. Teamtailor's free Self-Import pattern paces requests about 300 ms apart, with several requests per candidate. 100Hires leans on batch endpoints and removable limits for the same job.

100Hires' published case study documents Linc Healthcare moving 25 jobs and roughly 13,800 candidates from BetterTeam through the API.

The published spec is the clearest practical difference. An OpenAPI file plugs into Postman, code generators, and AI coding tools directly.

One key covers the REST API and the Zapier, Make, and n8n integrations. The official 100Hires MCP server connects separately over OAuth 2.1.

The MCP server is first-party and open source, and its repository documents 130 tools, a count that checks out against the README's own category totals.

Start a free 100Hires trial, generate an API key under Settings, Integrations, and pull the OpenAPI spec to explore every route.

Frequently asked questions

What is the rate limit for the Teamtailor API?

Teamtailor's own API reference documents 50 requests per 10 seconds, with HTTP 429 on breach and X-Rate-Limit headers; some third-party guides say no limit is published, and the official reference disproves them. The 100Hires API defaults to 100 requests per 10 minutes on new keys, and 100Hires can raise or remove the limit on request through support@100hires.com, depending on use case.

How do I get a Teamtailor API key?

In Teamtailor, a Company Admin creates keys under Settings, Integrations, API keys, choosing a scope (Public, Internal, or Admin) and access level. Keys cannot be edited after creation, so scope changes mean delete and recreate. In 100Hires, keys are generated self-serve under Settings, Integrations on every plan including the free trial.

Does the Teamtailor API support webhooks?

Company Webhooks are configured in the Teamtailor UI after activating the Add-on; the public API has no webhook endpoints, and Teamtailor's two documentation pages currently disagree on retry behavior, so build idempotent handlers. The 100Hires API manages webhooks via REST (create, list, delete, rotate secret; no update operation) with HMAC-signed deliveries per its OpenAPI spec.

Does Teamtailor have an MCP server?

Not a first-party one; an open-source community project, crunchloop/mcp-teamtailor, covers candidate retrieval. 100Hires runs an official hosted MCP server at mcp.100hires.com/mcp with OAuth 2.1 and 130 documented tools, with MIT-licensed source on GitHub.

Can I migrate data into Teamtailor through the API?

Yes. Teamtailor documents a free Self-Import pattern: pace requests about 300 ms apart, and expect several requests per candidate for custom fields, answers, and notes; support helps with process questions and errors. 100Hires supports API migration with batch endpoints and removable rate limits; 100Hires' published case study documents Linc Healthcare moving 25 jobs and roughly 13,800 candidates this way.

Is Teamtailor an ATS?

Yes. Teamtailor is an employer-branding-led applicant tracking system known for its career-site builder, with the API surfaces this guide covers. 100Hires is an ATS focused on AI screening, with an open REST API and a first-party MCP server.

What are the best API dev tools for working with ATS APIs?

For JSON:API services like Teamtailor's, Postman or any HTTP client plus a JSON:API-aware library covers most work. For OpenAPI-described services like the 100Hires API, the spec file at api.100hires.com/v2/openapi.json plugs straight into Postman, code generators, and AI coding tools.

What is an API in HR software?

An API is the contract that lets your scripts and systems read and write HR data such as candidates, jobs, and applications without touching the UI. It is the basis for integrations, migrations, and automation. Teamtailor exposes a JSON:API REST interface; 100Hires exposes a plain-JSON REST API plus webhooks and an MCP server for AI assistants.

Where to go from here

Building on Teamtailor day to day? Keep its three documentation sites bookmarked: docs.teamtailor.com for the reference, support.teamtailor.com for access and webhooks, and partner.teamtailor.com for partner integration options.

Evaluating ATS platforms on developer experience? The 100Hires REST API's self-serve keys, spec-first docs, API-managed webhooks, and first-party MCP server are the features to test - and the broader Teamtailor alternatives guide covers the rest of the field.

Start a free trial to try the API against real hiring data.

Related 100Hires resources: Explore recruiting software.