Receive real-time status updates as a background report moves through its lifecycle (queued, pending candidate consent, in progress, complete, or requiring action). GoodHire documents webhook notifications as the recommended way to avoid polling the Reports API; the callback payload shape is honestly modeled here.
openapi: 3.0.3
info:
title: GoodHire API
version: '1.0'
x-endpointsModeled: true
description: >-
RESTful, FCRA-compliant employment background check API for GoodHire (a Checkr
company). Background checks are ordered by creating a report object tied to a
candidate and a screening package (product bundle); status changes are delivered
via outbound webhooks. The API is split into a Customer API (a single company
ordering its own reports) and a Partner API (HR platforms ordering on behalf of
embedded employer requestors).
Access is gated - request an API key from api@goodhire.com and build against the
sandbox (https://api-sandbox.goodhire.com), which returns dummy report data,
before moving to production.
NOTE: This document mixes endpoints confirmed from GoodHire's public docs with
endpoints and schemas honestly modeled from documented resource patterns
(x-endpointsModeled: true). It is a discovery aid, not a byte-for-byte mirror of
GoodHire's official reference.
contact:
name: GoodHire API Team
email: api@goodhire.com
url: https://www.goodhire.com/api/
servers:
- url: https://api.goodhire.com
description: Production
- url: https://api-sandbox.goodhire.com
description: Sandbox (returns dummy report data)
security:
- ApiKeyAuth: []
tags:
- name: Reports
description: Order and track background check reports.
- name: Requestors
description: Manage the users who order and are associated with reports.
- name: Packages
description: List available screening packages (product bundles) and prices.
- name: Partner
description: Partner API app-access flow for embedded HR platforms.
paths:
/company/{company_id}/requestor/{requestor_id}/report/queue:
post:
tags:
- Reports
summary: Queue a background report
description: >-
Create and queue a new background check report for a candidate under a
given company and requestor, selecting the screening package and passing
candidate details plus request options (e.g. mark all info as submitted,
add billing codes, suppress the receipt email). Confirmed endpoint.
operationId: queueReport
parameters:
- $ref: '#/components/parameters/CompanyId'
- $ref: '#/components/parameters/RequestorId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ReportOrder'
responses:
'200':
description: Report queued
content:
application/json:
schema:
$ref: '#/components/schemas/Report'
'401':
$ref: '#/components/responses/Unauthorized'
/company/{company_id}/requestor/{requestor_id}/report/{report_id}:
get:
tags:
- Reports
summary: Get report status
description: Retrieve the status and available results of a report by ID. Confirmed endpoint.
operationId: getReport
parameters:
- $ref: '#/components/parameters/CompanyId'
- $ref: '#/components/parameters/RequestorId'
- name: report_id
in: path
required: true
schema:
type: string
responses:
'200':
description: Report
content:
application/json:
schema:
$ref: '#/components/schemas/Report'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
description: Report not found
/company/{company_id}/requestor/{requestor_id}/report:
get:
tags:
- Reports
summary: List reports
description: List reports for a requestor. Endpoint modeled from documented resource patterns (x-endpointsModeled).
operationId: listReports
x-endpointModeled: true
parameters:
- $ref: '#/components/parameters/CompanyId'
- $ref: '#/components/parameters/RequestorId'
responses:
'200':
description: A page of reports
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Report'
'401':
$ref: '#/components/responses/Unauthorized'
/company/{company_id}/requestor/{requestor_id}/productbundles:
get:
tags:
- Packages
summary: List product bundles (packages)
description: >-
Retrieve all screening packages (product bundles) available to the account
along with their prices. Confirmed endpoint.
operationId: listProductBundles
parameters:
- $ref: '#/components/parameters/CompanyId'
- $ref: '#/components/parameters/RequestorId'
responses:
'200':
description: Available packages
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ProductBundle'
'401':
$ref: '#/components/responses/Unauthorized'
/company/{company_id}/requestors:
get:
tags:
- Requestors
summary: List requestors
description: List requestors for a company. Endpoint modeled from documented resource patterns (x-endpointsModeled).
operationId: listRequestors
x-endpointModeled: true
parameters:
- $ref: '#/components/parameters/CompanyId'
responses:
'200':
description: A page of requestors
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Requestor'
post:
tags:
- Requestors
summary: Create a requestor
description: Provision a new requestor. Endpoint modeled from documented resource patterns (x-endpointsModeled).
operationId: createRequestor
x-endpointModeled: true
parameters:
- $ref: '#/components/parameters/CompanyId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Requestor'
responses:
'200':
description: Requestor created
content:
application/json:
schema:
$ref: '#/components/schemas/Requestor'
/company/{company_id}/requestor/{requestor_id}:
get:
tags:
- Requestors
summary: Get a requestor
description: Retrieve a single requestor. Endpoint modeled from documented resource patterns (x-endpointsModeled).
operationId: getRequestor
x-endpointModeled: true
parameters:
- $ref: '#/components/parameters/CompanyId'
- $ref: '#/components/parameters/RequestorId'
responses:
'200':
description: Requestor
content:
application/json:
schema:
$ref: '#/components/schemas/Requestor'
/company/{company_id}/requestor/{requestor_id}/partnerappaccess/stepselectreport:
post:
tags:
- Partner
summary: Partner app access - select report step
description: >-
Partner API flow step used by an embedded HR platform to select and
configure the report to be ordered on behalf of a requestor, with request
options customizing portions of the request. Confirmed endpoint.
operationId: partnerSelectReport
parameters:
- $ref: '#/components/parameters/CompanyId'
- $ref: '#/components/parameters/RequestorId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PartnerReportSelection'
responses:
'200':
description: Report selection accepted
content:
application/json:
schema:
$ref: '#/components/schemas/Report'
'401':
$ref: '#/components/responses/Unauthorized'
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: Authorization
description: 'API key sent as: Authorization: ApiKey <API_KEY>. Request keys from api@goodhire.com.'
parameters:
CompanyId:
name: company_id
in: path
required: true
schema:
type: string
RequestorId:
name: requestor_id
in: path
required: true
schema:
type: string
responses:
Unauthorized:
description: Missing or invalid API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
schemas:
Candidate:
type: object
description: The person being screened. Schema modeled from documented fields.
properties:
firstName:
type: string
lastName:
type: string
email:
type: string
format: email
phone:
type: string
ssn:
type: string
description: Provided when the requestor submits candidate info directly rather than via candidate self-consent.
ReportOrder:
type: object
description: Request body for queuing a report. Schema modeled from documented fields.
required:
- candidate
- productBundleId
properties:
candidate:
$ref: '#/components/schemas/Candidate'
productBundleId:
type: string
description: Identifier of the screening package to run.
requestOptions:
type: object
description: Options such as allInfoSubmitted, billingCode, or suppressReceiptEmail.
additionalProperties: true
Report:
type: object
description: A background check report. Schema modeled from documented fields.
properties:
id:
type: string
status:
type: string
enum:
- queued
- pending_candidate
- in_progress
- complete
- action_required
- canceled
result:
type: string
description: Overall outcome once complete (e.g. clear or needs review).
candidate:
$ref: '#/components/schemas/Candidate'
productBundleId:
type: string
createdAt:
type: string
format: date-time
completedAt:
type: string
format: date-time
ProductBundle:
type: object
description: A screening package available to the account, with price.
properties:
id:
type: string
name:
type: string
price:
type: number
description: Per-check price in USD.
screenings:
type: array
items:
type: string
Requestor:
type: object
description: A user who orders and is associated with reports.
properties:
id:
type: string
firstName:
type: string
lastName:
type: string
email:
type: string
format: email
PartnerReportSelection:
type: object
description: Partner API report selection payload. Schema modeled from documented fields.
properties:
productBundleId:
type: string
requestOptions:
type: object
additionalProperties: true
Error:
type: object
properties:
code:
type: string
message:
type: string
webhooks:
reportStatusChanged:
post:
summary: Report status changed
description: >-
Outbound HTTP callback GoodHire POSTs to the subscriber-configured URL when
a report changes status. Payload shape modeled from documented behavior
(x-endpointsModeled). This is a one-way HTTP webhook, not a WebSocket.
x-endpointModeled: true
requestBody:
content:
application/json:
schema:
type: object
properties:
event:
type: string
example: report.status_changed
report:
$ref: '#/components/schemas/Report'
responses:
'200':
description: Acknowledged by the subscriber