Quickstart

1. Create an API token

Sign in to JOIN as a System Admin.
Go to Settings → Developer → API tokens and select Create token.
Enter a name that identifies the integration, for example HRIS sync.
Copy the token from the confirmation dialog. It starts with join_sk_ and is shown only once.

Store the token in a secret manager or other safe storage.

❗️
Server-side only
A token grants read and write access to your company's data. Never embed it in a browser, a mobile app, or a public repository.

2. Make a first request

List your company's locations:

curl https://api.join.com/v3/locations \
  -H "Authorization: Bearer $JOIN_API_TOKEN"

{
  "data": [
    {
      "id": 1042,
      "name": "Berlin HQ",
      "address": {
        "countryCode": "DE",
        "city": "Berlin",
        "streetName": "Torstraße",
        "streetNumber": "49",
        "postalCode": "10119"
      },
      "establishmentId": null,
      "isDefault": true,
      "createdAt": "2024-03-11T09:12:44.000Z",
      "updatedAt": "2026-01-20T15:03:10.000Z"
    }
  ],
  "nextCursor": null
}

A 401 response means the token is missing or invalid. See Authentication.

3. Read the applications on a job

curl "https://api.join.com/v3/applications?jobId=4321&status=ACTIVE&limit=50" \
  -H "Authorization: Bearer $JOIN_API_TOKEN"

Each application carries the candidate summary, its status (ACTIVE, OFFER, HIRED, REJECTED), its currentPipelineStage, the submitted documents, and the screening answers. When nextCursor is not null, pass it as cursor to fetch the next page. See Pagination.

4. Add a candidate to a job

curl https://api.join.com/v3/applications \
  -X POST \
  -H "Authorization: Bearer $JOIN_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jobId": 4321,
    "externalId": "ats-77881",
    "candidate": {
      "firstName": "Ada",
      "lastName": "Lovelace",
      "email": "[email protected]",
      "countryCode": "GB"
    }
  }'

The response is 201 Created with the new application. It lands with status ACTIVE in the first review stage of the job's pipeline. If the email already belongs to one of your candidates, that candidate is reused rather than duplicated.

5. Move the application through the pipeline

Fetch the job's stages, then move the application to one of them:

curl https://api.join.com/v3/jobs/4321/pipeline \
  -H "Authorization: Bearer $JOIN_API_TOKEN"

curl https://api.join.com/v3/applications/98765/pipeline-stage \
  -X PUT \
  -H "Authorization: Bearer $JOIN_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "pipelineStageId": 55012 }'

The move behaves like dragging the card between columns in JOIN: the application's status follows the stage type, and your pipeline automations run.

Next steps

Errors: the codes to handle in production.
Rate limits: how to stay within your quota.
API Reference: every endpoint and field.