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

# Search candidates

`POST /hiring/candidates/search`

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/sourceMismatchSeverity` 'none' | 'resolved' | 'low' | 'high' — Severity level of source mismatch (if any). Possible values:<br /> <ul> <li><code>none</code> – None</li> <li><code>resolved</code> – Resolved</li> <li><code>low</code> – Low</li> <li><code>high</code> – High</li> </ul>
    - `/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/candidateConfirmedExtendedConsent` boolean — Whether the candidate confirmed extended consent
    - `/candidate/candidateNeedsToBeManuallyDeleted` boolean — Whether the candidate needs to be manually deleted
    - `/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/dataDeletionDate` string, date — Scheduled date for data deletion
    - `/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.net/hibob/apis/employee-data-api.md) · [All operations](https://skmtc.net/hibob/apis/employee-data-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/hibob/employee-data-api/revisions/0781ebbdda91/schema)