Overview

The Hiring module in Bob helps you manage recruitment end to end, from opening roles and publishing job ads to tracking candidates and applications.

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

• Retrieve candidates and their attributes
• Fetch job openings and their details
• Read applications and their current status
• Fetch job ads to power a custom careers page and route applicants to Bob’s application form

Common use cases include:

• Powering a custom careers page using job ads and job openings from Hiring
• Building internal dashboards and analytics that combine hiring data with other sources

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

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

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:

• Job openings are the internal hiring requisitions in Bob. Job ads are the published representation.
• Use the opening ID as the join key when matching applications and job ads back to the role.

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.

Job ads

A job ad is the public-facing representation of a job opening on your careers page or job boards. Job ads control what candidates see when they browse open roles.

Typical fields include:

• Job ad title and description
• Location and employment details derived from the underlying job opening
• Visibility and promotion settings
• jobAd/applyUrl, which links to the hosted application form

Integration notes:

• 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

flowchart TB
		direction TB
		PO["Job opening"]
		JA["Job ad"]
		C["Candidate"]
		A["Application"]

	PO -->|publishes| JA
	JA -->|applyUrl routes to form| A
	C -->|submits| A
	PO -->|receives| A

The Hiring objects relate to each other as follows:

• Job openings represent roles you are hiring for.
• Candidates represent people in your hiring pipeline.
• Applications link a candidate to a specific job opening and track the candidate’s progress (stage and status).
• Job ads are the public-facing postings for an opening that can appear on your careers page and job boards.

Typical relationships:

• A job opening can have one or more job ads.
• A job ad includes an applyUrl that routes a candidate to Bob’s hosted application form, which creates an application.
• A candidate can have one or more applications.
• Each application references exactly one candidate and one job opening.

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.

Endpoints

Use these endpoints to search and read hiring resources data.

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 and aggregate by opening, stage, and time to understand pipeline health.

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