---
title: "Search candidates"
method: POST
path: "/hiring/candidates/search"
tags: ["Candidates"]
---

# Search candidates

`POST /hiring/candidates/search`

## Request

- Base URL: `https://api.hibob.com/v1`
- URL: `https://api.hibob.com/v1/hiring/candidates/search`
- Auth: one of:
  - HTTP basic
  - HTTP bearer

Searches candidates using filters and returns paginated results.

<ul>
  <li>Use the <code>fields</code> parameter to specify which fields to return</li>
  <li>Use the <code>filters</code> parameter to narrow down results</li>
  <li>Use cursor-based pagination with <code>limit</code> and <code>cursor</code></li>
</ul>

<p><b>Testing notes</b>:</p>
<ul>
  <li>Use the testing widget's <b>Try It!</b> option to test this endpoint.</li>
  <li>Use the <b>Examples > Request Example</b> option to see how to initiate body parameters.</li>
</ul>

## Request body

- CandidateSearchRequest
  - `fields` string[], required: Required list of field IDs to include in the response (1–50 fields). The property must be provided; if omitted or not provided, the API returns an error. You must explicitly choose which fields to fetch. For all available field IDs, see the <code>fields</code> object defined on each item in the 200 response schema.
  - `filters` object[]
    - `fieldId` '/candidate/id' | '/candidate/email' | '/candidate/firstName' | '/candidate/lastName' | '/candidate/modificationDate', required: Field ID to filter by
    - `operator` 'equals' | 'notEqual' | 'greaterThan' | 'lessThan', required: Filter operator. Use 'equals'/'notEqual' for exact matching. Use 'greaterThan'/'lessThan' for date range filtering (e.g. modificationDate).
    - `values` union[], required
      - union
        - string
        - number
  - `limit` integer
  - `cursor` string
  - `includeArchived` boolean

## Response `200`

Successfully retrieved candidates

- CandidateSearchResponse
  - `items` CandidateSearchResponseObject[], required: Array of candidate objects
    - `/candidate/id` integer: Unique identifier for the candidate
    - `/candidate/firstName` string: First name
    - `/candidate/lastName` string: Last name
    - `/candidate/email` string, email: Email address
    - `/candidate/phone` string: Phone number
    - `/candidate/title` string: Professional title
    - `/candidate/address` string: Address
    - `/candidate/photo` object: Candidate photo data.
      - `fileId` integer: Internal file ID
      - `url` string: URL to the photo image
      - `scanId` string: Virus scan ID (UUID)
      - `status` 'processing' | 'processed' | 'rejected' | 'failed': Photo processing status
    - `/candidate/languages` object[]: Languages spoken by the candidate
      - `/candidateLanguage/language` string: Language code (e.g. en, he, es)
      - `/candidateLanguage/proficiency` 'native' | 'expert' | 'advanced' | 'upper intermediate' | 'intermediate' | 'foundational' | 'beginner': Proficiency level. Possible values:<br /> <ul> <li><code>native</code> – Native</li> <li><code>expert</code> – Expert</li> <li><code>advanced</code> – Advanced</li> <li><code>upper intermediate</code> – Upper intermediate</li> <li><code>intermediate</code> – Intermediate</li> <li><code>foundational</code> – Foundational</li> <li><code>beginner</code> – Beginner</li> </ul>
    - `/candidate/skills` object[]: Candidate skills
      - `/candidateSkills/skillName` string: Skill name
    - `/candidate/socialMedia` string: Social media URL (legacy field)
    - `/candidate/socialMediaLinkedIn` string: LinkedIn profile URL
    - `/candidate/socialMediaFacebook` string: Facebook profile URL
    - `/candidate/socialMediaInstagram` string: Instagram profile URL
    - `/candidate/socialMediaThreads` string: Threads profile URL
    - `/candidate/socialMediaTwitter` string: Twitter/X profile URL
    - `/candidate/socialMediaYouTube` string: YouTube channel URL
    - `/candidate/socialMediaMedium` string: Medium profile URL
    - `/candidate/socialMediaGitHub` string: GitHub profile URL
    - `/candidate/socialMediaReddit` string: Reddit profile URL
    - `/candidate/socialMediaXing` string: Xing profile URL
    - `/candidate/socialMediaPersonalWebsite` string: Personal website URL
    - `/candidate/country` string: Country
    - `/candidate/city` string: City
    - `/candidate/region` string: Region or state
    - `/candidate/education` object[]: Education history entries. Each item uses candidate education field IDs as keys.
      - `/candidateEducation/school` string: School or institution name
      - `/candidateEducation/fieldOfStudy` string: Field of study or major
      - `/candidateEducation/degree` string: Degree type (e.g. "B.Sc", "M.A.", "Ph.D.")
      - `/candidateEducation/startDate` string, date: Start date (YYYY-MM-DD)
      - `/candidateEducation/startDateDay` integer: Day component of the start date
      - `/candidateEducation/startDateMonth` integer: Month component of the start date
      - `/candidateEducation/startDateYear` integer: Year component of the start date
      - `/candidateEducation/endDate` string, date: End date (YYYY-MM-DD)
      - `/candidateEducation/endDateDay` integer: Day component of the end date
      - `/candidateEducation/endDateMonth` integer: Month component of the end date
      - `/candidateEducation/endDateYear` integer: Year component of the end date
    - `/candidate/experience` object[]: Work experience entries. Each item uses candidate experience field IDs as keys.
      - `/candidateExperience/title` string: Job title
      - `/candidateExperience/company` string: Company name
      - `/candidateExperience/industry` string: Industry
      - `/candidateExperience/summary` string: Role description or summary
      - `/candidateExperience/startDate` string, date: Start date (YYYY-MM-DD)
      - `/candidateExperience/startDateDay` integer: Day component of the start date
      - `/candidateExperience/startDateMonth` integer: Month component of the start date
      - `/candidateExperience/startDateYear` integer: Year component of the start date
      - `/candidateExperience/endDate` string, date: End date (YYYY-MM-DD)
      - `/candidateExperience/endDateDay` integer: Day component of the end date
      - `/candidateExperience/endDateMonth` integer: Month component of the end date
      - `/candidateExperience/endDateYear` integer: Year component of the end date
      - `/candidateExperience/isCurrent` boolean: Whether this is the current position
      - `/candidateExperience/durationDays` integer: Duration in days (calculated from start/end dates)
    - `/candidate/employeeId` string: Associated Bob employee ID (if the candidate was hired).<br /><br />To read this employee, use <a href="https://apidocs.hibob.com/reference/post_people-identifier" target="_blank">Read company employee fields by employee ID ↗</a>.
    - `/candidate/externalUserId` string: External user ID
    - `/candidate/importExternalId` string: External ID from import
    - `/candidate/sourceId` string: Source identifier
    - `/candidate/sourceEffectiveDate` string, date-time: Effective date of the candidate source
    - `/candidate/extendConsentDueDate` string, date-time: Due date for extended consent request
    - `/candidate/extendedConsentRequestedAt` string, date-time: Timestamp when extended consent was requested
    - `/candidate/anonymizedAt` string, date-time: Timestamp when the candidate was anonymized
    - `/candidate/jobOpeningsToApplicationIds` object[]: Mapping of job opening IDs to application IDs for this candidate.<br /><br />To fetch job openings, use <a href="https://apidocs.hibob.com/reference/post_hiring-job-openings-search" target="_blank">Search job openings ↗</a>. To fetch applications, use <a href="https://apidocs.hibob.com/reference/post_hiring-applications-search" target="_blank">Search applications ↗</a>.
      - `jobOpening` integer: Job opening ID.<br /><br />To fetch the job opening, use <a href="https://apidocs.hibob.com/reference/post_hiring-job-openings-search" target="_blank">Search job openings ↗</a>.
      - `applicationIds` integer[]: Application IDs for this job opening.<br /><br />To fetch applications, use <a href="https://apidocs.hibob.com/reference/post_hiring-applications-search" target="_blank">Search applications ↗</a>.
    - `/candidate/dataDownloadFileId` string: File ID for downloaded candidate data
    - `/candidate/dataDownloadRequestedAt` string, date-time: Timestamp when data download was requested
    - `/candidate/dataDeletionRequestedAt` string, date-time: Timestamp when data deletion was requested
    - `/candidate/dataDownloadedAt` string, date-time: Timestamp when data was downloaded
    - `/candidate/sourceType` 'api' | 'api_internal' | 'free_job_board' | 'paid_job_board' | 'my_contracts_job_board' | 'referral' | 'agency' | 'agency_archived' | 'manual_upload' | 'custom_campaign' | 'custom_job_board' | 'custom_social' | 'referral_import' | 'referral_internal' | 'copied_from_job_opening' | 'sourced_by' | 'candidate_database' | 'opn_network': Sourcing channel type. Possible values:<br /> <ul> <li><code>api</code> – External Career page</li> <li><code>api_internal</code> – Internal Career page</li> <li><code>free_job_board</code> – Free job board</li> <li><code>paid_job_board</code> – Paid job board</li> <li><code>my_contracts_job_board</code> – My contracts job board</li> <li><code>referral</code> – Referral</li> <li><code>agency</code> – Agency</li> <li><code>agency_archived</code> – Agency (legacy)</li> <li><code>manual_upload</code> – Manual upload</li> <li><code>custom_campaign</code> – Custom Campaign</li> <li><code>custom_job_board</code> – Custom Job Board</li> <li><code>custom_social</code> – Social media</li> <li><code>referral_import</code> – Referral (import)</li> <li><code>referral_internal</code> – Referral internal</li> <li><code>copied_from_job_opening</code> – Copied from job opening</li> <li><code>sourced_by</code> – Sourced by</li> <li><code>candidate_database</code> – Candidate database</li> <li><code>opn_network</code> – OPN Network</li> </ul>
    - `/candidate/sourceApplicationId` number: Source application ID.<br /><br />To fetch the application, use <a href="https://apidocs.hibob.com/reference/post_hiring-applications-search" target="_blank">Search applications ↗</a>.
    - `/candidate/sourceInstanceId` number: Source instance ID
    - `/candidate/meetingBotEnabled` boolean: Whether the meeting bot is enabled for this candidate
    - `/candidate/modificationDate` string, date-time: Timestamp of the last modification to this candidate record
  - `response_metadata` object, required
    - `next_cursor` string, nullable: Cursor for next page. Null if no more results.

## Other responses

- `400`: Bad Request - Invalid parameters
- `401`: Unauthorized - Invalid or missing credentials
- `403`: Forbidden - IP not allowed or feature not enabled
- `429`: Rate limit exceeded
- `500`: Internal server error

---

[API](https://skmtc.dev/hibob/apis/bob-hiring-api.md) - [All operations](https://skmtc.dev/hibob/apis/bob-hiring-api/llms.txt) - [OpenAPI document](https://skmtc.dev/hibob/apis/bob-hiring-api/revisions/c758e371fc83?raw)