> For the complete documentation index, see [llms.txt](https://help.join.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.join.com/integrations-and-api/api-documentation.md).

# API documentation

Create a JOIN API token, authenticate requests to the JOIN API v3, and learn how versions, rate limits, pagination and errors work.

{% hint style="info" %}
**Who can use this**

* **Plans:** Advanced and Enterprise
* **Roles:** System Admins
  {% endhint %}

## Get started

This reference helps you get started with the JOIN API v3, JOIN's REST API. The API allows you to interact with your JOIN data programmatically – for example, to fetch job listings, retrieve applications, or manage candidate records.

The JOIN API is stateless, meaning each request must include authentication and does not rely on prior interactions. To use the API, you’ll need to create an API token in JOIN.

All v3 requests go to `https://api.join.com/v3`.

<a href="https://docs.join.com/reference/getting-started" class="button primary">Read full API documentation</a>

***

## Authentication

To validate your API requests, JOIN requires an API token. The token belongs to your company, not to a single user. It only gives access to your company's data in JOIN.

JOIN API access, including API credentials and token generation, is available only on the `Advanced` and `Enterprise` plans.

{% hint style="info" %}
Can't see the `Developer` page? Only System Admins can open it. If `Create token` opens an upgrade prompt, check your plan: click your name in the bottom-left corner, select `Settings`, then select `Billing`. Upgrade to `Advanced` or `Enterprise` to use JOIN API and generate credentials.

See [Subscription plans](/plans-and-billing/subscription-plans.md) for plan details and upgrade guidance.
{% endhint %}

### Generate an API token

1. Click your name in the bottom-left corner and select `Settings`.
2. Select `Developer`.
3. Click `Create token`, enter a name, and copy the token from the window that opens. It is shown only once.

Your company can have up to 10 active tokens.

{% hint style="warning" %}
Keep your API token secure. It provides access to your company data in JOIN, including the ability to read, update or delete information.
{% endhint %}

### Use the API token

Send your token in the `Authorization` header of every request, as a Bearer token: `Authorization: Bearer join_sk_…`. New tokens start with `join_sk_`.

A request without a token returns `401 authentication_required`. A token that is invalid or revoked, or used on a plan without API access, returns `401 token_invalid`.

### Choose an API version

The JOIN API v3 is versioned by date. Send the `Join-Version` header to choose a version. Without it, JOIN uses `2026-11-01`. An unknown version returns `400 unsupported_api_version`.

We recommend sending `Join-Version` on every request, so your integration keeps working when a new version is released. See [Versions and compatibility](https://docs.join.com/reference/versioning-and-depreciation).

**Example request:**

```bash
curl -X GET \
  https://api.join.com/v3/jobs \
  -H 'Authorization: Bearer your-api-token-here' \
  -H 'Join-Version: 2026-11-01'
```

### Revoke an API token

You can revoke a token at any time in `Settings` → `Developer`. Keep in mind that:

* Once revoked, the token stops working immediately
* Tokens cannot be reactivated or regenerated
* You must update your integration with a new token if one is revoked

***

## Rate limits, pagination and errors

* **Rate limits:** each token can send 600 requests a minute, and at most 100 in any 10 seconds. Above that, the API returns `429 rate_limit_exceeded` with a `Retry-After` header that says when to try again.
* **Pagination:** lists return 10 records by default, and `limit` accepts 1 to 50. To get the next page, send the response's `nextCursor` as `cursor`. On the last page, `nextCursor` is `null`.
* **Errors:** every error comes as `{"error": {"code", "message", "details"}}`. `details` names the fields that failed validation.

For details, see [Rate limits](https://docs.join.com/reference/rate-limits), [Pagination, filtering and sorting](https://docs.join.com/reference/pagination) and [Responses, errors and retries](https://docs.join.com/reference/requests-and-responses).

***

## JOIN API v2

JOIN API v2 is deprecated. Build new integrations on v3, and plan to move existing v2 integrations to v3.

* Existing v2 API keys were migrated to company tokens automatically. Their values didn't change, so your v2 integrations keep working. You find them in `Settings` → `Developer`, named after the admin who owned the key.
* New tokens you create in `Developer` also work on v2.

To move an integration from v2 to v3, see [Moving from v2 to v3](https://docs.join.com/reference/migration-guide-from-v2).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://help.join.com/integrations-and-api/api-documentation.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.