Getting started with the ATS API

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

Prerequisites

• A Deel account with ATS enabled
• An API token with ats:read and ats:write scopes. See 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 by including a teams array in the request body:

$
curl --request POST 'https://api.letsdeel.com/rest/v2/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. Retrieve their UUIDs to use in ATS calls:

$
curl --request GET 'https://api.letsdeel.com/rest/v2/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.

$
curl --request GET 'https://api.letsdeel.com/rest/v2/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.

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

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.

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

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.

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

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.

$
curl --request GET 'https://api.letsdeel.com/rest/v2/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.

$
curl --request GET 'https://api.letsdeel.com/rest/v2/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.

Next steps