Retrieve paginated list of ATS Candidates | Deel

curl -G https://api.letsdeel.com/rest/ats/candidates \
     -H "Authorization: Bearer <token>" \
     -d current_stage_category_type_slugs=phone-screen \
     -d current_stage_default_type_slugs=technical-interview \
     -d current_stage_default_type_slugs=others \
     -d cursor=cursorValue \
     -d department_ids=a1b2c3d4-e5f6-7890-1234-567890abcdef \
     -d job_ids=a1b2c3d4-e5f6-7890-1234-567890abcdef \
     -d limit=50 \
     -d locations=GB \
     --data-urlencode locations=CA:London \
     --data-urlencode "search=John Doe" \
     -d source_slugs=linkedin \
     -d source_slugs=referral \
     -d tag_ids=a1b2c3d4-e5f6-7890-1234-567890abcdef \
     -d team_ids=a1b2c3d4-e5f6-7890-1234-567890abcdef \
     --data-urlencode updated_after=2025-06-18T00:00:00.000Z

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
      "email": "john.doe@example.com",
      "last_name": "Doe",
      "created_at": "2023-10-01T12:00:00Z",
      "first_name": "John",
      "numeric_id": 12345,
      "updated_at": "2023-10-02T12:00:00Z",
      "city": "Berlin",
      "source": "LINKEDIN",
      "pic_url": "https://example.com/profile.jpg",
      "imported_id": "ext-123",
      "applications": [
        {
          "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
          "job": {
            "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
            "title": "Software Engineer"
          },
          "created_at": "2024-01-02T00:00:00Z",
          "current_application_interview_plan_stage": {
            "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
            "status": "ACTIVE",
            "created_at": "2024-01-03T00:00:00Z",
            "application_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
            "interview_plan_stage_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
            "interview_plan_stage": {
              "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
              "name": "Phone Screen",
              "stage_order": 1,
              "interview_plan_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
              "category_type_slug": "initial",
              "description": "Initial phone screening with the candidate",
              "default_type_slug": "phone-screen"
            }
          }
        }
      ],
      "country_code": "DE",
      "phone_number": "+15551234567",
      "anonymized_at": "2024-01-01T00:00:00Z",
      "candidate_tags": [],
      "import_session_id": "session-123",
      "origin_source_slug": "sourced_internally",
      "final_archivation_at": "2024-01-04T00:00:00Z",
      "linkedin_profile_url": "https://www.linkedin.com/in/johndoe",
      "total_applications_count": 5
    }
  ],
  "has_more": true,
  "next_cursor": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "total_count": 100
}

Lists the candidates of the organization that the caller may see. Use it to find a candidate before reading or updating them, or to keep an external system in sync by fetching only the candidates changed since its last run.

Token scopes: ats:read, worker:read

Authentication

AuthorizationBearer

Authentication

The Deel API uses bearer tokens to authenticate requests. All API calls must be made over HTTPS — calls over plain HTTP or without authentication will fail.

curl -X GET 'https://api.deel.training/rest/v2/contracts' \
  -H 'Authorization: Bearer YOUR-TOKEN-HERE'

Learn more about authentication

AuthorizationBearer

Standard OAuth2 security scheme based on https://swagger.io/docs/specification/authentication/

Query parameters

cursorstringOptional

The cursor for pagination

limitintegerOptional1-100Defaults to 20

Maximum number of records returned in one response

searchstringOptional

Search text for filtering candidates

job_idslist of stringsOptional

Filter candidates by job IDs

department_idslist of stringsOptional

Filter candidates by department IDs

tag_idslist of stringsOptional

Filter candidates by tag IDs

current_stage_category_type_slugslist of stringsOptional

Filter candidates by current stage category type slugs

current_stage_default_type_slugslist of stringsOptional

Filter candidates by current stage default type slugs

updated_afterstringOptionalformat: "date-time"

Filter applications updated after this timestamp (ISO 8601 format)

source_slugslist of stringsOptional

Return only candidates with at least one application from one of these sources (slugs from the application sources endpoint).

team_idslist of stringsOptional

Return only candidates with at least one application to a job of one of these teams.

locationslist of stringsOptional

Return only candidates located in one of these places. Each value is an ISO 3166-1 alpha-2 country code (GB) or a country code and city separated by a colon (GB:London); a city is never matched without its country.

Response

Successful operation.

datalist of objects

List of candidates

has_moreboolean

Indicates if there are more items to fetch

next_cursorstring or null

Cursor for the next page of results

total_countinteger>=0

Total number of candidates

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

500

Internal Server Error