---
updatedAt: 2026-05-11T14:42:06.000Z
---

Fetch the complete documentation index at: https://apidocs.hibob.com/llms.txt. Use this file to discover all available pages before exploring further. Append .md to any documentation page URL to get its markdown version.

# Explore Hiring API 

Understand the basic concepts of hiring data and workflows and how to use them with the Public API

# Overview

The Hiring module in Bob helps you manage recruitment end to end: internal requisitions and pipeline work on one side, and published careers listings and applies on the other—alongside tracking candidates and applications.

The **Hiring API** provides programmatic access to core hiring data so you can:

* Retrieve **candidates**, including profile dimensions such as education, experience, skills, and languages
* Fetch **job openings** and their details
* Read **applications**, **application form answers**, and their current status
* Search **interviews**, **evaluations**, and **evaluation scorecard templates** tied to the pipeline
* Search **offers** linked to applications and openings
* Fetch **job ads** to power a custom careers page and route applicants to Bob’s application form

Common use cases include:

* Publishing roles and driving applies from a **custom careers page** (job ads API)
* Running **internal hiring operations**: requisitions, pipeline tracking, and analytics tied to **job openings**, candidates, and applications
* Combining Hiring data with other sources in BI or HR tools

# Before you begin

* Ensure your account has the [**Hiring** module](https://www.hibob.com/talent/hiring/) enabled.
* Create an **API service user** and generate an access token. To learn more, see [Getting started with the Public API](https://apidocs.hibob.com/docs/getting-started).
* Configure the service user’s **permissions** (see [Required permissions](#required-permissions)).

# Key concepts

<Accordion title="Candidates">
  <p>A <strong>candidate</strong> represents a person in the hiring pipeline.</p>
  <p><strong>Typical fields include:</strong></p>

  <ul>
    <li>Personal details such as name and contact information</li>
    <li>Source information (for example, job board, referral, or careers page)</li>
    <li>Tags or labels used for reporting and segmentation</li>
    <li>Links to one or more applications</li>
  </ul>

  <p><strong>Candidate profile data (Hiring core):</strong> Beyond the main candidate record, you can search related profile entities—such as <strong>education</strong>, <strong>work experience</strong>, <strong>skills</strong>, <strong>languages</strong>, <strong>volunteer experience</strong>, <strong>professional associations</strong>, and <strong>qualifications or licenses</strong>—using dedicated search endpoints. Use these to build a full resume-style view or to sync structured CV data into another system.</p>

  <p><strong>Integration notes:</strong></p>

  <ul>
    <li>Use the <strong>candidate ID</strong> as your primary identifier. Email addresses are attributes that can change.</li>
    <li>A candidate can submit <strong>multiple applications</strong> (for different openings), so treat the relationship as 1:N.</li>
    <li>Candidates who apply via a job ad’s <code>applyUrl</code> are submitted through Bob’s hosted form and appear in Bob Hiring with the appropriate source (for example, Careers page).</li>
    <li>Filter candidate profile searches by candidate ID (and other fields where supported) to align child records with the parent candidate.</li>
  </ul>

  <p><strong>Endpoints:</strong> See <a href="#hiring-api-endpoints">Hiring API endpoints</a> below.</p>
</Accordion>

<Accordion title="Job openings">
  <p>A <strong>job opening</strong> (often referred to as a job or requisition) is a role you are actively hiring for.</p>
  <p><strong>Typical fields include:</strong></p>

  <ul>
    <li>Title and description</li>
    <li>Department, site, and hiring manager</li>
    <li>Employment type (such as full-time or part-time)</li>
    <li>Status (for example, open, on hold, or closed)</li>
  </ul>

  <p><strong>Integration notes:</strong></p>

  <ul>
    <li>Use job openings for <strong>internal requisition</strong> workflows: status, ownership, headcount, and matching applications to the role you are hiring for.</li>
    <li>Use the <strong>opening ID</strong> as the stable join key for applications, pipeline reporting, and integrations that mirror Bob’s hiring workflow.</li>
  </ul>

  <p><strong>Endpoints:</strong> See <a href="#hiring-api-endpoints">Hiring API endpoints</a> below.</p>
</Accordion>

<Accordion title="Applications">
  <p>An <strong>application</strong> links a candidate to a specific job opening and tracks progress through the hiring workflow.</p>
  <p><strong>Typical fields include:</strong></p>

  <ul>
    <li>Candidate identifier</li>
    <li>Job opening identifier</li>
    <li>Current <strong>stage</strong> and status (for example, Screening, Interview, Offer, Hired, Rejected)</li>
    <li>Key timestamps such as created date and last updated date</li>
  </ul>

  <p><strong>Integration notes:</strong></p>

  <ul>
    <li>Each application links <strong>one candidate</strong> to <strong>one job opening</strong> (candidate + opening is the core relationship).</li>
    <li>Stages represent the steps in the pipeline. Status represents the overall state or outcome.</li>
    <li>Use timestamps (created / updated) for incremental sync and analytics when available in filters and responses.</li>
  </ul>

  <p><strong>Endpoints:</strong> See <a href="#hiring-api-endpoints">Hiring API endpoints</a> below.</p>
</Accordion>

<Accordion title="Application form answers">
  <p><strong>Application form answers</strong> store responses candidates submitted on hiring application forms (custom questions configured for your process).</p>
  <p>Use search to retrieve answers by application, form, or question identifiers so you can export screening data, drive integrations, or reconcile responses with your ATS.</p>
  <p><strong>Endpoints:</strong> See <a href="#hiring-api-endpoints">Hiring API endpoints</a> below.</p>
</Accordion>

<Accordion title="Interviews">
  <p>An <strong>interview</strong> is a scheduled or recorded interaction for an application—such as type, status, timing, participants, and conferencing details when applicable.</p>
  <p>Search interviews to report on pipeline activity, sync calendars or downstream tools, or audit who interviewed whom and when.</p>
  <p><strong>Endpoints:</strong> See <a href="#hiring-api-endpoints">Hiring API endpoints</a> below.</p>
</Accordion>

<Accordion title="Evaluations">
  <p>An <strong>evaluation</strong> captures structured feedback on a candidate or interview step. Evaluations have a <strong>type</strong> in the product and API—not only scorecards—including scorecard-style evaluations when configured (for example recommendation, score, and linkage to an application).</p>
  <p><strong>Evaluation scorecard templates</strong> are the reusable template definitions (linked questionnaire / scorecard structure) that evaluations can use; they describe the definition Hiring applies when running scorecard-type evaluations.</p>
  <p><strong>Endpoints:</strong> See <a href="#hiring-api-endpoints">Hiring API endpoints</a> below.</p>
</Accordion>

<Accordion title="Offers">
  <p>An <strong>offer</strong> represents the formal offer stage for an application—typically including status, dates, and compensation-related fields as exposed in the API.</p>
  <p><strong>Endpoints:</strong> See <a href="#hiring-api-endpoints">Hiring API endpoints</a> below.</p>
</Accordion>

<Accordion title="Job ads">
  <p>A <strong>job ad</strong> powers the <strong>careers-site and external publishing</strong> workflow: what applicants see on your careers page or syndicated boards, how roles are promoted, and where they click to apply.</p>
  <p><strong>Typical fields include:</strong></p>

  <ul>
    <li>Job ad title and description</li>
    <li>Location and employment details shown to candidates</li>
    <li>Visibility and promotion settings</li>
    <li><code>jobAd/applyUrl</code>, which links to the hosted application form</li>
  </ul>

  <p><strong>Integration notes:</strong></p>

  <ul>
    <li>Treat job ads as an <strong>apply and syndication surface</strong>, not the same workflow as managing requisitions in Bob (see Job openings).</li>
    <li>Use <code>jobAd/applyUrl</code> as the canonical “Apply” link. Submitting the form creates an application in Bob.</li>
    <li>Use job ad visibility (for example, active vs inactive) to decide what to show on an external careers page.</li>
  </ul>

  <p><strong>Endpoints:</strong> See <a href="#hiring-api-endpoints">Hiring API endpoints</a> below.</p>
  <p>To learn how to use these endpoints to integrate with your external careers page, including examples of filters, fields, and URL patterns, see <a href="https://apidocs.hibob.com/docs/how-to-use-hiring-api-careers-page">Integrate with your Careers page</a>.</p>
</Accordion>

# Data model and relationships

Internal **requisition and pipeline** flow (job openings, candidates, applications):

```mermaid
flowchart TB
	direction TB
	PO["Job opening"]
	C["Candidate"]
	A["Application"]

	C -->|submits| A
	PO -->|receives| A
```

**Careers site** apply path (job ads route candidates into applications):

```mermaid
flowchart LR
	JA["Job ad"]
	A["Application"]

	JA -->|applyUrl| A
```

Records tied to an **application** (interviews, evaluations, offers, and application form answers):

```mermaid
flowchart TD
	APP["Application"]
	INT["Interviews"]
	EVAL["Evaluations"]
	OFFER["Offers"]
	FA["Application form answers"]

	APP -- has --> INT
	APP -- has --> EVAL
	APP -- has --> OFFER
	APP -- has --> FA
```

**Job openings**, **evaluations**, and **evaluation scorecard templates**:

```mermaid
flowchart TD
	JO["Job opening"]
	EVAL["Evaluations"]
	SCT["Scorecard templates"]

	JO -- configures --> SCT
	EVAL -- uses definition --> SCT
```

**Internal hiring (requisitions and pipeline)**

* **Job openings** are the roles you manage inside Bob as requisitions.
* **Candidates** represent people in your hiring pipeline.
* **Applications** link a candidate to a specific job opening and track progress (stage and status).
* A **candidate** can have one or more **applications**.
* Each **application** references exactly one **candidate** and one **job opening**.

**Careers site and external publishing (job ads)**

* **Job ads** are what you surface to applicants on a careers page or boards.
* A job ad’s **`applyUrl`** sends candidates into Bob’s hosted application form and creates an **application**—that path is distinct from day‑to‑day requisition management in the UI or API.

**Hiring core** adds searchable records that hang off the pipeline:

* **Application form answers** belong to an application and capture responses to configured application questions.
* **Interviews** and **evaluations** are associated with applications (and related openings or candidates as exposed in each endpoint’s fields).
* **Offers** tie to applications (and typically candidates and openings) for the offer stage.
* **Candidate profile** entities (education, experience, and similar) extend the candidate record for richer CV-style data.

# Hiring Public API

This section summarizes the main data types and endpoints you will typically use with the Hiring API.

## Resources

| Data type                      | Description                                                                                            | Example use cases                                                                   |
| ------------------------------ | ------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- |
| Candidates                     | People in the hiring pipeline                                                                          | Sync candidate records, enrich profiles, reporting                                  |
| Candidate profile data         | Education, experience, skills, languages, and related CV-style entities per candidate                  | Full-profile sync, screening analytics, matching tools                              |
| Job openings                   | Internal requisitions for roles you are hiring for                                                     | Headcount reporting, pipeline analytics, sync with internal ATS or planning tools   |
| Applications                   | Links between candidates and specific job openings                                                     | Track pipeline stages, drive downstream automations                                 |
| Application form answers       | Responses to questions on hiring application forms                                                     | Export screening answers, integrate with external ATS or assessment tools           |
| Interviews                     | Scheduled or completed interviews for applications                                                     | Calendar sync, interviewer workload, pipeline analytics                             |
| Evaluations                    | Structured feedback submissions (typed in product/API; includes scorecard-style evaluations when used) | Quality-of-hire reporting, sync hiring decisions                                    |
| Evaluation scorecard templates | Reusable scorecard or questionnaire definitions used by evaluations                                    | Discover which template applies, align reporting with configured scorecards         |
| Offers                         | Offer-stage records for applications                                                                   | Time-to-offer metrics, handoff to HRIS or payroll prep                              |
| Job ads                        | Published postings and apply links for external candidates                                             | Custom careers page, syndication, route applicants to Bob’s hosted application form |

To learn more, see [Key concepts](#key-concepts).

## Hiring API endpoints

Use these endpoints to search and read Hiring data.

**Hiring core** POST `…/search` endpoints—the operations listed under **Candidates and candidate profile data**, **Applications**, **Interviews, evaluations, and offers**, and **Job openings** below—typically support field selection, filters, and cursor-based pagination. Check each endpoint’s reference for exact parameters and behavior.

### Candidates and candidate profile data

| Action                                                 | Endpoint                                                                                                                                                         | Description                                                |
| ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| Search candidates                                      | [Search candidates](https://apidocs.hibob.com/reference/post_hiring-candidates-search)                                                                           | Retrieve candidates by filters and pagination.             |
| Search candidate educations                            | [Search candidate educations](https://apidocs.hibob.com/reference/post_hiring-candidate-educations-search)                                                       | Retrieve education records (filter by candidate and more). |
| Search candidate experiences                           | [Search candidate experiences](https://apidocs.hibob.com/reference/post_hiring-candidate-experiences-search)                                                     | Retrieve work experience records.                          |
| Search candidate languages                             | [Search candidate languages](https://apidocs.hibob.com/reference/post_hiring-candidate-languages-search)                                                         | Retrieve language proficiency records.                     |
| Search candidate skills                                | [Search candidate skills](https://apidocs.hibob.com/reference/post_hiring-candidate-skills-search)                                                               | Retrieve skill entries.                                    |
| Search candidate volunteer experiences                 | [Search candidate volunteer experiences](https://apidocs.hibob.com/reference/post_hiring-candidate-volunteer-experiences-search)                                 | Retrieve volunteer experience records.                     |
| Search candidate professional associations memberships | [Search candidate professional associations memberships](https://apidocs.hibob.com/reference/post_hiring-candidate-professional-associations-memberships-search) | Retrieve professional association memberships.             |
| Search candidate qualifications licenses               | [Search candidate qualifications licenses](https://apidocs.hibob.com/reference/post_hiring-candidate-qualifications-licenses-search)                             | Retrieve qualifications and licenses.                      |

### Applications

| Action                          | Endpoint                                                                                                           | Description                                               |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------- |
| Search applications             | [**Search applications**](https://apidocs.hibob.com/reference/post_hiring-applications-search)                     | Retrieve applications (for example, by opening or stage). |
| Search application form answers | [Search application form answers](https://apidocs.hibob.com/reference/post_hiring-application-form-answers-search) | Retrieve answers tied to applications and form questions. |

### Interviews, evaluations, and offers

| Action                                | Endpoint                                                                                                                       | Description                                         |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------- |
| Search interviews                     | [Search interviews](https://apidocs.hibob.com/reference/post_hiring-interviews-search)                                         | Retrieve interview records for applications.        |
| Search evaluations                    | [Search evaluations](https://apidocs.hibob.com/reference/post_hiring-evaluations-search)                                       | Retrieve evaluation and scorecard submissions.      |
| Search evaluation scorecard templates | [Search evaluation scorecard templates](https://apidocs.hibob.com/reference/post_hiring-evaluation-scorecard-templates-search) | Retrieve evaluation scorecard template definitions. |
| Search offers                         | [Search offers](https://apidocs.hibob.com/reference/post_hiring-offers-search)                                                 | Retrieve offer records linked to the pipeline.      |

### Job openings

| Action              | Endpoint                                                                                       | Description                       |
| ------------------- | ---------------------------------------------------------------------------------------------- | --------------------------------- |
| Search job openings | [**Search job openings**](https://apidocs.hibob.com/reference/post_hiring-job-openings-search) | Retrieve job openings by filters. |

### Job ads

| Action              | Endpoint                                                                                                       | Description                                                |
| ------------------- | -------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| Get all job ads     | [Get all active job ads from your Career page](https://apidocs.hibob.com/reference/post_hiring-job-ads-search) | Retrieve active job ads and choose which fields to return. |
| Get a single job ad | [Get the details of a single job ad](https://apidocs.hibob.com/reference/get_hiring-job-ads-id)                | Retrieve full details for one job ad.                      |

## Required permissions

Before accessing hiring data, ensure the service user has permission to access the relevant information, just as you would when assigning permissions to a user in Bob.

* The service user should have the Features > Hiring system settings > Job opening > Manage all job openings.

<br />

# Common Hiring API workflows

## Power a custom careers page (job ads)

1. Search job ads to retrieve the open roles to display.
2. Render each job ad on your careers site.
3. Use `jobAd/applyUrl` to route candidates to Bob’s hosted application form.

For a step-by-step guide, examples of fields and filters, and URL patterns, see [**Integrate with your Careers page**](https://apidocs.hibob.com/docs/how-to-use-hiring-api-careers-page).

## Sync Hiring data to another system (BI)

A common approach is to:

1. Search **candidates** and **applications** using filters.
2. Store IDs in your system so you can match records reliably.
3. Re-run searches periodically and update downstream systems when data changes.

## Build analytics and dashboards

Search **applications**, **interviews**, **evaluations**, or **offers** and aggregate by opening, stage, and time to understand pipeline health and outcomes beyond basic funnel counts.

## Best practices

* **Permissions:** Use the same principle as in the Bob UI: if a person cannot see a candidate or application in Bob, the service user should not be able to retrieve it via the API.
* **Pagination:** When using search endpoints, implement paging and persist your paging state, especially for large tenants.
* **IDs over emails:** Use stable identifiers (candidate ID, opening ID, application ID) as your primary keys. Treat emails as attributes that can change.
* **Incremental sync:** Prefer filtering by relevant “updated at” fields when available, to avoid full re-syncs.

# Related resources

Use these resources to continue:

* [Hiring API reference](https://apidocs.hibob.com/reference/hiring)
* [Integrate with your Careers page](https://apidocs.hibob.com/docs/how-to-use-hiring-api-careers-page) (Hiring API careers‑page integration)
* [Explore Employee data API](https://apidocs.hibob.com/docs/explore-employee-data) – for linking hired candidates to employee records
* [Getting started with the Public API](https://apidocs.hibob.com/docs/getting-started)
* [Rate limiting](https://apidocs.hibob.com/reference/rate-limiting)

# Sibling pages

* [Explore Employee data API](https://apidocs.hibob.com/docs/explore-employee-data.md)
* [Explore Time off API](https://apidocs.hibob.com/docs/explore-time-off-api.md)
* [Explore Attendance API](https://apidocs.hibob.com/docs/explore-attendance-api.md)
* [Explore Tasks API](https://apidocs.hibob.com/docs/explore-tasks.md)
* [Explore Reports API](https://apidocs.hibob.com/docs/explore-reports.md)
* [Explore Docs API](https://apidocs.hibob.com/docs/explore-docs-api.md)
* [Explore Bob Skills API](https://apidocs.hibob.com/docs/explore-skills-api.md)
* [Explore Employer API](https://apidocs.hibob.com/docs/explore-employer-api.md)
* [Explore Goals API](https://apidocs.hibob.com/docs/explore-goals-api.md)
* [Explore Learning API ](https://apidocs.hibob.com/docs/explore-learning-lms-api.md)
* [Explore Job catalog API](https://apidocs.hibob.com/docs/explore-job-catalog-api.md)
* [Explore Workforce planning API](https://apidocs.hibob.com/docs/explore-workforce-planning.md)