Overview

Bob's Applicant API lets Marketplace partners, typically Applicant Tracking Systems (ATS), and also EOR or onboarding providers, push a hired candidate into Bob’s existing ATS Pending Hires flow.

The Applicant API integration is the end-to-end Marketplace partner flow that combines OAuth installation, partner-owned setup and field mapping, metadata and document folder discovery, and the applicant submission.

With the Applicant API integration, you can:

• Onboard a customer via Marketplace OAuth, with no manual token or Hire API connection setup in Bob
• Discover Bob employee field metadata and document folders to power your setup UI
• Submit hired-candidate fields, including required identity fields, optional mapped fields, and documents
• Optionally sync open job positions from Bob into your ATS using existing Workforce Planning APIs

Common use cases include:

• Building a Marketplace ATS integration that pushes new hires into Bob
• Migrating a partner integration off the legacy Hire API onto Marketplace OAuth

How it works

The integration is a partner-push model:

1. One-time setup per company: Customer installs your app → OAuth consent → Bob redirects to your setup URL → you fetch field and folder metadata → customer maps fields and picks a document folder in your UI → you store the config and tokens.
2. Per new hire: When a candidate is marked hired in your system, you POST one applicant with Bob field IDs and optional documents.
3. In Bob: The record appears in ATS Pending Hires. Configured notification recipients are alerted. HR approves and runs the existing New Hire flow to create the employee.

sequenceDiagram
    participant Customer
    participant Partner as Partner ATS
    participant Bob
    Note over Customer,Bob: One-time setup
    Customer->>Bob: Install Marketplace app + OAuth consent
    Bob-->>Partner: Redirect to partner setup URL (company_id)
    Partner->>Bob: GET /v1/company/people/fields
    Partner->>Bob: GET /v1/docs/folders/metadata
    Customer->>Partner: Map ATS fields → Bob field IDs, select folder
    Note over Partner: Store mapping, folderId, tokens
    Note over Customer,Bob: Per hire
    Customer->>Partner: Candidate marked hired
    Partner->>Bob: POST /v1/external-hires/applicants
    Bob-->>Partner: 201 Created (empty body)
    Bob->>Customer: Pending Hires + notification
    Customer->>Bob: Approve → New Hire flow → employee created

Before you begin

• Confirm you are an approved Marketplace partner with Developer Portal access
• Create a Marketplace app
• Configure OAuth Redirect URI
• Add the scopes in Required permissions and scopes
• Implement OAuth token exchange, refresh, and per-company token storage — see OAuth 2.0 and Managing customer installations

Bob does not show a Bob-owned configuration screen for Applicant API apps. You own the setup experience after install.

Key concepts

Core workflows

Workflow 1: One-time partner setup

Use this when a customer installs your app from Marketplace:

1. Customer clicks Install → OAuth consent for your requested scopes.
2. Bob redirects to your First-time setup URL with company_id and a short-lived session token.
3. Exchange the auth code for access_token + refresh_token and store them per company. See OAuth 2.0.
4. Call Get all employee fields (GET /v1/company/people/fields) to build your field-mapping UI.
5. Call Get list of folders with metadata (GET /v1/docs/folders/metadata) so the customer can pick a destination folder (folderId).
6. In your UI, let the customer:
   • Map their ATS fields → Bob field IDs
   • Select the document folder for hire attachments
   • Confirm that any mapped fields they expect to populate are included in their Bob New Hire flow
7. Store mapping + folderId on your side, not in Bob. The Marketplace installation shows as connected.

sequenceDiagram
    participant Customer
    participant Partner
    participant Bob
    Customer->>Bob: Install + authorize scopes
    Bob-->>Partner: Setup redirect (company_id)
    Partner->>Bob: Exchange code for tokens
    Partner->>Bob: GET /v1/company/people/fields
    Partner->>Bob: GET /v1/docs/folders/metadata
    Customer->>Partner: Complete mapping + folder selection
    Note over Partner: Persist config per company

Workflow 2: Submit a hired candidate

This is the primary recurring flow:

1. Candidate is marked hired in your ATS, or equivalent.
2. Build the payload from your stored field mapping.
3. Call POST /v1/external-hires/applicants with Authorization: Bearer <access_token>.
4. On 201, the pending hire is created in Bob. There is no applicant ID in the response.
5. HR reviews Pending Hires, approves, and completes the New Hire flow.

Include at least the required fields. Attach documents only when you have a public or signed URL and a valid numeric folderId.

Workflow 3 (optional): Sync open positions into your ATS

Independently of Applicant API, ATS partners can sync Bob open positions using Workforce Planning APIs, for example Search position openings.

This is optional. Request the Workforce Planning scopes that cover the endpoints you call — see Scopes mapping to endpoints and Explore Workforce Planning.

Required and recommended fields

Partners must send these under fields. A well-formed payload missing either returns 422:

Strongly encourage customers to map and send:

Documents

Documents are optional. When present, each item requires:

Obtain valid folderId values during setup via Get list of folders with metadata.

Applicant API Endpoint

Base URL: https://api.hibob.com

Example request

POST /v1/external-hires/applicants HTTP/1.1
Host: api.hibob.com
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "fields": {
    "root.firstName": "Jane",
    "root.surname": "Smith",
    "root.email": "[email protected]",
    "work.startDate": "2026-09-01",
    "work.title": "Senior Engineer",
    "work.department": "Engineering",
    "work.siteId": "London",
    "payroll.salary.payment": {
      "value": 85000,
      "currency": "GBP"
    },
    "payroll.salary.payPeriod": "Annual"
  },
  "documents": [
    {
      "name": "CV.pdf",
      "url": "https://storage.partner.com/cv_jane.pdf",
      "folderId": 2010547
    }
  ]
}

Success response

201 Created with an empty body. No applicant ID is returned.

Errors

Responses use the standard API error body: code, message, details, request_id.

Example 422:

{
  "code": "unprocessable_entity",
  "message": "Missing required field.",
  "details": {
    "missing": ["root.surname"]
  },
  "request_id": "b7c1f0e2-..."
}

Supporting endpoints

Partners commonly use these endpoints during setup or for optional ATS features:

Required permissions and scopes

This API supports OAuth only. Service users are not supported.

Select scopes in the Developer Portal scope picker. They are not auto-enabled. See Scopes mapping to endpoints.

The customer company must install your Marketplace app and approve the requested scopes.

Rate limits

• Proposed limit: 10 requests per minute per company + app, companyId + app user.
• On limit exceeded: 429 with rate-limit / Retry-After headers.

Final limits may change after load testing during the early-access program.

Partner journey checklist

1. Create a standard app in the Developer Portal
2. Select applicants:write, company.metadata:read, and documents:read, plus any optional scopes
3. Configure OAuth Redirect URI, First-time setup URL, and Manage URL
4. Implement OAuth, token storage, refresh, and your setup UI, including field mapping and folder picker
5. Implement POST /v1/external-hires/applicants on hire events, with retries for 429 / 500
6. Test in Marketplace Dev mode: install → map fields → push a test hire → confirm Pending Hires
7. Submit the app for review; approved apps are listed under Marketplace applicant integrations

Migrating from the Hire API

If you have already shipped a Hire API integration, token, or service user, read this before building Applicant API support.

What stays the same for customers

What changes for partners

There is no automated migration of legacy connections. You publish a Marketplace app based on OAuth and Applicant API; each customer installs it and re-completes mapping in your product when they are ready, and sets up notifications in Bob.

Timeline

1. Applicant API launch — New Marketplace partner integrations must use Applicant API OAuth. Legacy Hire API remains fully operational for existing connections.
2. Launch + 6 months — Creating new token-based Hire API connections is blocked / removed from the Bob UI. Existing token-based and service-user Hire API connections keep working and remain manageable.
3. Voluntary cutover — Encourage customers on your legacy connection to install your Marketplace app when you support Applicant API. Run both in parallel until their install is live, then retire the old connection on their side when ready.

Partner migration checklist

1. Create a Marketplace app with applicants:write, company.metadata:read, and documents:read, plus any optional scopes.
2. Partner rebuilds setup: OAuth install → fetch people-fields and folders metadata → develop a field-mapping UI where customers map ATS fields to Bob ids and select folderId.
3. Rewrite the hire push to POST /v1/external-hires/applicants with the flat fields payload. Required: root.firstName, root.surname.
4. Map document handling to include folderId on every attachment.
5. Test with a pilot company in Marketplace Dev mode: install → map → push a hire → confirm Pending Hires.
6. Publish the Marketplace app and share install / cutover steps with existing Hire API customers.
7. Keep supporting the legacy connection until those customers have cut over, or until product policy requires otherwise.

Legacy developer reference: Integrate with ATS (Hire API).

Best practices

• Own setup in your product — Bob will not provide mapping or folder UI for Applicant API apps
• Always send field id values from people-fields metadata, including the root. prefix for Basic info fields
• Store folderId from setup and send it on every document; use a JSON number
• Keep document URLs reachable long enough for Bob to download. Signed URLs are fine if still valid
• Treat 201 empty body as success — keep your own correlation IDs for support and idempotency
• Refresh OAuth tokens and cache them per installing company
• Back off on 429 and retry 500
• Tell customers that notifications are set up in Bob’s ATS Pending Hires UI for all Applicant API apps. To learn more, see ATS Pending Hires Notifications.
• For OAuth and installation lifecycle, see Managing customer installations

Related resources

• Quick start guide — create and submit a Marketplace app
• OAuth 2.0 — authorization code flow, tokens, and uninstall
• Scopes mapping to endpoints
• Get all employee fields
• Get list of folders with metadata
• Explore Workforce Planning — optional open-position sync
• Integrate with ATS (Hire API) — legacy Hire API developer guide
• Become a partner — join the HiBob partner program