> This page is for API, version 2026-01-01 (Stable) (default).
> For other versions, use one of these documentation indexes:
> - 2026-01-01 (Stable) (default): https://developer.deel.com/api/stable/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developer.deel.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer.deel.com/_mcp/server.

# Getting started with the ATS API

> How to authenticate, retrieve required reference data, and make your first ATS API call.

This guide outlines the setup steps required before you can create jobs or applications via the ATS API.

> **Note**
>
> Missing reference data causes most integration failures. Teams, locations, and employment types must exist in your organization and you need their IDs before making POST requests.

## Prerequisites

* A Deel account with ATS enabled
* An API token with `ats:read` and `ats:write` scopes. See [Authentication](/api/authentication) for setup instructions.
* The `organizations:write` scope if you need to create teams (see below).

## About team IDs

Jobs require at least one `team_id`. Define your teams in the Deel App under **Organization settings -> Organization -> Groups**, or via [`POST /hris/organization_structures`](/api/hris-endpoints/organization-structure/create-organization-structure) by including a `teams` array in the request body:

#### Request

```bash
curl --request POST 'https://api.letsdeel.com/rest/hris/organization_structures' \
  --header 'Authorization: Bearer YOUR-TOKEN-HERE' \
  --header 'Content-Type: application/json' \
  --data '{
    "data": {
      "name": "Engineering",
      "teams": [
        { "name": "Platform" },
        { "name": "Infrastructure" }
      ]
    }
  }'
```

Once created, those teams appear immediately in [`GET /teams`](/api/reference/endpoints/organizations/get-teams-v-2026-01-01). Retrieve their UUIDs to use in ATS calls:

#### Request

```bash
curl --request GET 'https://api.letsdeel.com/rest/teams' \
  --header 'Authorization: Bearer YOUR-TOKEN-HERE'
```

If teams already exist in your organization, skip the creation step and go straight to `GET /teams`.

## Step 1: Verify authentication

Confirm your token has the correct scopes by calling a lightweight read endpoint.

#### Request

```bash
curl --request GET 'https://api.letsdeel.com/rest/ats/employment-types' \
  --header 'Authorization: Bearer YOUR-TOKEN-HERE' \
  --header 'Content-Type: application/json'
```

A `200` response confirms authentication is working. A `401` means your token is missing or invalid. A `403` means your token lacks the `ats:read` scope.

## Step 2: Retrieve locations

Jobs require at least one location. Fetch all available locations and store the IDs you will use.

#### Request

```bash
curl --request GET 'https://api.letsdeel.com/rest/ats/locations' \
  --header 'Authorization: Bearer YOUR-TOKEN-HERE'
```

#### Response

```json
{
  "data": [
    {
      "id": "loc_01hxyz123abc",
      "name": "Remote — Global"
    },
    {
      "id": "loc_01hxyz456def",
      "name": "New York, USA"
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "total_count": 2
}
```

Store the `id` values for locations you will assign to jobs.

## Step 3: Retrieve employment types

Both job creation and application creation require an employment type.

#### Request

```bash
curl --request GET 'https://api.letsdeel.com/rest/ats/employment-types' \
  --header 'Authorization: Bearer YOUR-TOKEN-HERE'
```

#### Response

```json
{
  "data": [
    {
      "id": "et_01hxyz789ghi",
      "name": "Full-time"
    },
    {
      "id": "et_01hxyzabcjkl",
      "name": "Contract"
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "total_count": 2
}
```

## Step 4: Retrieve your hiring member ID

Some operations, such as advancing an application through an interview plan stage, require a `creator_id`. This is your HRIS organization user ID.

#### Request

```bash
curl --request GET 'https://api.letsdeel.com/rest/ats/hiring-members' \
  --header 'Authorization: Bearer YOUR-TOKEN-HERE'
```

#### Response

```json
{
  "data": [
    {
      "id": "hm_01hxyz111mno",
      "hris_organization_user_id": "hrou_01hxyz222pqr"
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "total_count": 1
}
```

Store the `hris_organization_user_id`. You will use it as `creator_id` when associating applications with interview plan stages.

## Step 5: Retrieve departments (optional)

Departments are optional on jobs but useful for filtering and reporting.

#### Request

```bash
curl --request GET 'https://api.letsdeel.com/rest/ats/departments' \
  --header 'Authorization: Bearer YOUR-TOKEN-HERE'
```

## Pagination

All list endpoints use cursor-based pagination. Use the `next_cursor` value from a response as the `cursor` query parameter in the next request.

#### Request

```bash
curl --request GET 'https://api.letsdeel.com/rest/ats/jobs?cursor=NEXT_CURSOR_VALUE&limit=50' \
  --header 'Authorization: Bearer YOUR-TOKEN-HERE'
```

Check `has_more` in each response to determine whether additional pages exist.

> **Tip**
>
> Fetch and cache reference data (locations, employment types, departments) at integration startup rather than on every request. These values change infrequently.

## Next steps

#### [Manage jobs](/api/ats-guides/manage-jobs)

Create job openings using the reference IDs you just retrieved.

#### [Candidates and applications](/api/ats-guides/manage-candidates-and-applications)

Create candidates and submit applications.

#### [Authentication](/api/authentication)

Learn how to generate and manage API tokens.

#### [ATS overview](/api/ats-guides/introduction)

Review the full ATS data model and known limitations.