---
title: "Search candidates"
method: GET
path: "/candidates"
tags: ["candidates"]
---

# Search candidates

`GET /candidates`

## Request

- Base URL: `https://api.smartrecruiters.com`
- URL: `https://api.smartrecruiters.com/candidates`
- Auth: one of:
  - API key in header `x-smarttoken`
  - OAuth 2
    - Authorization code: `https://www.smartrecruiters.com/identity/oauth/allow`
    - Token URL: `https://api.smartrecruiters.com/identity/oauth/token` scopes: `candidates_read`

Only candidates matching all specified criteria and having at least one job application are returned.

## Query parameters

- `q` string
- `limit` integer
- `pageId` string
- `jobId` string[]
- `location` string[]
- `averageRating` integer[]
- `status` string[]
- `consentStatus` ConsentStatus[]
- `subStatus` string
- `tag` string[]
- `updatedAfter` string, date-time
- `onboardingStatus` 'READY_TO_ONBOARD' | 'ONBOARDING_SUCCESSFUL' | 'ONBOARDING_FAILED'
- `propertyId` string[]
- `propertyValueId` string[]
- `sourceType` string[]
- `sourceSubType` string[]
- `sourceValueId` string[]
- `questionCategory` string[]
- `questionFieldId` string[]
- `questionFieldValueId` string[]

## Response `200`

Candidates matching search criteria

- Candidates
  - `limit` integer, required
  - `nextPageId` string
  - `totalFound` integer, required
  - `content` Candidate[], required
    - `id` string, required
    - `internal` boolean, required: true, if the candidate has at least one internal application
    - `firstName` string, required
    - `lastName` string, required
    - `email` string
    - `createdOn` string, date-time, required
    - `updatedOn` string, date-time
    - `location` CandidateLocation
      - `country` string
      - `countryCode` string
      - `regionCode` string
      - `region` string
      - `city` string
      - `lat` number, float
      - `lng` number, float
    - `averageRating` number
    - `tags` string[]
    - `consent` object
      - `status` 'REQUIRED' | 'PENDING' | 'ACQUIRED': * **REQUIRED** - no request for consent yet, * **PENDING** - consent requested, * **ACQUIRED** - consent provided by a candidate
    - `primaryAssignment` object
      - `job` object, required
        - `id` string, required
        - `title` string, required
        - `actions` object, required
          - `details` Action, required
            - `url` string, required
            - `method` 'GET' | 'POST' | 'PUT' | 'PATCH' | 'OPTIONS' | 'DELETE' | 'HEAD' | 'CONNECT', required
      - `status` 'LEAD' | 'NEW' | 'IN_REVIEW' | 'INTERVIEW' | 'OFFERED' | 'HIRED' | 'REJECTED' | 'WITHDRAWN' | 'TRANSFERRED', required
      - `subStatus` string
    - `secondaryAssignments` object[]
      - `job` object, required
        - `id` string, required
        - `actions` object, required
          - `details` Action, required
            - `url` string, required
            - `method` 'GET' | 'POST' | 'PUT' | 'PATCH' | 'OPTIONS' | 'DELETE' | 'HEAD' | 'CONNECT', required
    - `actions` object, required
      - `details` Action, required
        - `url` string, required
        - `method` 'GET' | 'POST' | 'PUT' | 'PATCH' | 'OPTIONS' | 'DELETE' | 'HEAD' | 'CONNECT', required
      - `properties` Action, required
        - `url` string, required
        - `method` 'GET' | 'POST' | 'PUT' | 'PATCH' | 'OPTIONS' | 'DELETE' | 'HEAD' | 'CONNECT', required

## Other responses

- `400`: with codes * **FIELDS_CRITERIA_SIZE_VIOLATED** when number of elements of query param `propertyId` is not equal to number of elements of query param `propertyValueId` * **SOURCES_CRITERIA_SIZE_VIOLATED** when number of elements of query param `sourceType` is not equal to number of elements of query param `sourceSubType` or not equal to number of elements of query param `sourceValueId` * **SCREENING_QUESTIONS_CRITERIA_SIZE_VIOLATED** when number of elements of query param `questionCategory` is not equal to number of elements of query param `questionFieldId` or not equal to number of elements of query param `questionFieldValueId` * **ONBOARDING_STATUS_NOT_ACTIVE** when Onboarding Status candidate property is not activated or user's company does not have candidate property feature, but user has requested to search candidates by onboardingStatus query parameter

---

[API](https://skmtc.dev/smartrecruiters/apis/candidates-api.md) - [All operations](https://skmtc.dev/smartrecruiters/apis/candidates-api/llms.txt) - [OpenAPI document](https://skmtc.dev/smartrecruiters/apis/candidates-api/revisions/8fde9b33d46d?raw)