Overview

Assessments in Bob Hiring let recruiters order an assessment for a candidate, select a partner package, and track status and results in the hiring workflow.

The Assessments API is the partner-facing Public API for marketplace assessment providers.

Use it to:

• Register your package catalog for each installing company
• Receive assessment lifecycle events when a recruiter orders or cancels an assessment
• Fetch assessment context (candidate, requester, job opening, package, and request time)
• Report status and results back to Bob
  

Common use cases include:

• Onboarding a company after Marketplace install and publishing your assessment packages
• Starting a provider-side assessment when Bob sends assessment.triggered
• Updating Bob as the assessment progresses or completes
• Stopping work when Bob sends assessment.cancelled

Before you begin

• Confirm you are an approved Marketplace partner with Developer Portal access.
• See Testing notes for more details on how to create and configure your OAuth app before you can test it.

Key concepts

How it works

The integration follows a notify-then-pull, then push-back model:
1. Setup (once per company): After the user installs your app, register your packages.
2. Event notification: Bob sends a webhook when a recruiter orders or cancels an assessment.
3. Pull context: On assessment.triggered, call GET details with assessmentRequestId.
4. Run the assessment in your provider system.
5. Push updates: PATCH status and results as the assessment progresses or completes.
6. On cancel: Stop processing. Do not send further PATCH updates.
Bob does not call partner APIs. Partners always initiate GET, PATCH, and package calls after receiving a webhook or during setup.

Packages setup

sequenceDiagram
    participant Partner
    participant HiBob as Bob
    Partner->>HiBob: POST /hiring/assessments/packages
    HiBob-->>Partner: 201 Created
    Note over Partner,HiBob: Idempotent catalog replace per company

Assessment lifecycle

sequenceDiagram
    participant HiBob as Recruiter in Bob
    participant Partner
    participant Provider as Partner provider system
    HiBob->>HiBob: Order assessment (select package)
    HiBob-->>Partner: Webhook assessment.triggered (IDs + packageId)
    Partner->>HiBob: GET /hiring/assessments/{assessmentRequestId}
    HiBob-->>Partner: Candidate, requester, job opening, packageId
    Partner->>Provider: Submit assessment
    Provider-->>Partner: Progress / completion
    Partner->>HiBob: PATCH /hiring/assessments/{assessmentRequestId}
    HiBob-->>Partner: 204 No Content
    HiBob-->>HiBob: Updated status in UI

Cancellation

sequenceDiagram
    participant HiBob as Recruiter in Bob
    participant Partner
    HiBob->>HiBob: Cancel assessment
    HiBob-->>Partner: Webhook assessment.cancelled (assessmentRequestId only)
    Note over Partner: Stop processing. Do not PATCH further updates.

Required permissions

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

Assessments API endpoints

Webhooks

Bob delivers outbound events to your registered HTTPS webhook URL. Requests are signed — verify authenticity using the Bob-Signature header. See How Bob calculates the signature and Getting started with partner webhooks.
Delivery is at-least-once. Handle duplicate deliveries idempotently using assessmentRequestId.

{
  "version": "v2",
  "type": "assessment.triggered",
  "triggeredBy": "emp-001",
  "triggeredAt": "2026-05-28T10:00:00Z",
  "data": {
    "assessmentRequestId": "12345",
    "packageId": "test-coding-101"
  }
}

Example assessment.cancelled payload (same envelope; packageId is not included):

{
  "version": "v2",
  "type": "assessment.cancelled",
  "triggeredBy": "emp-001",
  "triggeredAt": "2026-05-28T11:00:00Z",
  "data": {
    "assessmentRequestId": "12345"
  }
}

Testing notes

Before you test an assessment integration, complete the basic app setup in the Developer Portal. See the Quick start guide for general app setup instructions.

Before testing, make sure your app includes:

• App listing details — add the provider name and description that should appear in Bob. For the full live listing, Overview comes from App listing details in the Developer Portal; About comes from the external Tech Partner Overview form. See Complete listing content for Overview and About in the Quick start guide.
• Logo — upload the logo Bob should show on the provider tile.
• Marketplace category — choose Candidate assessments as the integration type.
• OAuth configuration — request the hiring.integrations:write scope and configure the redirect URL used for testing.
• Webhook listener URL — register the HTTPS endpoint that will receive assessment.triggered and assessment.cancelled events.
  After you save these details, install the app in the test company, register your package catalog, and confirm that the provider appears as an available assessment option in Bob Hiring.

Related resources