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 enabled.
• Create an API service user and generate an access token. To learn more, see Getting started with the Public API.
• Configure the service user’s permissions (see Required permissions).

Key concepts

Candidates

A candidate represents a person in the hiring pipeline.

Typical fields include:

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

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

Integration notes:

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

Endpoints: See Hiring API endpoints below.

Job openings

A job opening (often referred to as a job or requisition) is a role you are actively hiring for.

Typical fields include:

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

Integration notes:

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

Endpoints: See Hiring API endpoints below.

Applications

An application links a candidate to a specific job opening and tracks progress through the hiring workflow.

Typical fields include:

• Candidate identifier
• Job opening identifier
• Current stage and status (for example, Screening, Interview, Offer, Hired, Rejected)
• Key timestamps such as created date and last updated date

Integration notes:

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

Endpoints: See Hiring API endpoints below.

Application form answers

Application form answers store responses candidates submitted on hiring application forms (custom questions configured for your process).

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.

Endpoints: See Hiring API endpoints below.

Interviews

An interview is a scheduled or recorded interaction for an application—such as type, status, timing, participants, and conferencing details when applicable.

Search interviews to report on pipeline activity, sync calendars or downstream tools, or audit who interviewed whom and when.

Endpoints: See Hiring API endpoints below.

Evaluations

An evaluation captures structured feedback on a candidate or interview step. Evaluations have a type in the product and API—not only scorecards—including scorecard-style evaluations when configured (for example recommendation, score, and linkage to an application).

Evaluation scorecard templates are the reusable template definitions (linked questionnaire / scorecard structure) that evaluations can use; they describe the definition Hiring applies when running scorecard-type evaluations.

Endpoints: See Hiring API endpoints below.

Offers

An offer represents the formal offer stage for an application—typically including status, dates, and compensation-related fields as exposed in the API.

Endpoints: See Hiring API endpoints below.

Job ads

A job ad powers the careers-site and external publishing workflow: what applicants see on your careers page or syndicated boards, how roles are promoted, and where they click to apply.

Typical fields include:

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

Integration notes:

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

Endpoints: See Hiring API endpoints below.

To learn how to use these endpoints to integrate with your external careers page, including examples of filters, fields, and URL patterns, see Integrate with your Careers page.

Data model and relationships

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

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):

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

	JA -->|applyUrl| A

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

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:

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

To learn more, see 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

Applications

Interviews, evaluations, and offers

Job openings

Job ads

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.

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.

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
• Integrate with your Careers page (Hiring API careers‑page integration)
• Explore Employee data API – for linking hired candidates to employee records
• Getting started with the Public API
• Rate limiting