Send candidates a hosted invitation to submit their own information and consent, then create, list, retrieve, and cancel those invitations. Invitations order a package once the candidate completes the flow, removing the need to collect PII directly.
openapi: 3.0.3
info:
title: Checkr API
description: >-
The Checkr API is a RESTful interface for running compliant employment
background checks. Employers, staffing firms, and platform partners create
candidates, send invitations, order packages, and retrieve reports composed
of individual screenings - SSN trace, county/state/national/federal criminal
searches, sex offender registry, motor vehicle records, and education /
employment verifications. The API also covers adverse action workflows,
subscriptions and continuous checks, node/hierarchy and geo account
structure, documents, Form I-9, and webhooks for event-driven report status
updates. Authentication is HTTP Basic auth with your secret API key as the
username and an empty password; Checkr Partner integrations use OAuth. All
responses are JSON. This document models the widely used, publicly
documented endpoints; it is not exhaustive of every screening type Checkr
offers.
version: '1.0'
contact:
name: Checkr
url: https://checkr.com
termsOfService: https://checkr.com/terms-of-service
servers:
- url: https://api.checkr.com/v1
description: Production
- url: https://api.checkr-staging.com/v1
description: Staging
security:
- basicAuth: []
tags:
- name: Candidates
description: Candidate records that background checks are run against.
- name: Invitations
description: Hosted invitations for candidates to submit their own information.
- name: Reports
description: The container aggregating a candidate's screenings and result.
- name: Screenings
description: Individual screening components nested under a report.
- name: Verifications
description: Education and employment verification screenings.
- name: Packages
description: Bundles of screenings and the programs that group them.
- name: Documents
description: Files attached to a candidate.
- name: Adverse Actions
description: FCRA adverse action workflows against a report.
- name: Subscriptions
description: Recurring re-runs of a package for a candidate.
- name: Continuous Checks
description: Ongoing monitoring for new records.
- name: Nodes and Hierarchy
description: Tree of nodes modeling account/organization structure.
- name: Geos
description: State/locale definitions scoping pricing and compliance.
- name: Webhooks
description: Event notification subscriptions.
- name: Account
description: Account and user metadata.
paths:
/candidates:
get:
operationId: listCandidates
tags: [Candidates]
summary: List candidates
parameters:
- $ref: '#/components/parameters/Page'
- $ref: '#/components/parameters/PerPage'
responses:
'200':
description: A paginated list of candidates.
content:
application/json:
schema:
$ref: '#/components/schemas/CandidateList'
'401':
$ref: '#/components/responses/Unauthorized'
post:
operationId: createCandidate
tags: [Candidates]
summary: Create a candidate
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CandidateCreate'
responses:
'201':
description: The created candidate.
content:
application/json:
schema:
$ref: '#/components/schemas/Candidate'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
/candidates/{id}:
parameters:
- $ref: '#/components/parameters/ResourceId'
get:
operationId: getCandidate
tags: [Candidates]
summary: Retrieve a candidate
responses:
'200':
description: The candidate.
content:
application/json:
schema:
$ref: '#/components/schemas/Candidate'
'404':
$ref: '#/components/responses/NotFound'
post:
operationId: updateCandidate
tags: [Candidates]
summary: Update a candidate
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CandidateCreate'
responses:
'200':
description: The updated candidate.
content:
application/json:
schema:
$ref: '#/components/schemas/Candidate'
delete:
operationId: deleteCandidatePII
tags: [Candidates]
summary: Request PII removal for a candidate
responses:
'200':
description: PII removal requested.
/candidates/{id}/documents:
parameters:
- $ref: '#/components/parameters/ResourceId'
get:
operationId: listCandidateDocuments
tags: [Documents]
summary: List candidate documents
responses:
'200':
description: A list of documents.
content:
application/json:
schema:
$ref: '#/components/schemas/DocumentList'
post:
operationId: uploadCandidateDocument
tags: [Documents]
summary: Upload a candidate document
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
properties:
file:
type: string
format: binary
type:
type: string
description: The document type, e.g. driver_license or motor_vehicle_report.
responses:
'201':
description: The uploaded document.
content:
application/json:
schema:
$ref: '#/components/schemas/Document'
/candidates/{id}/documents/{document_id}:
parameters:
- $ref: '#/components/parameters/ResourceId'
- name: document_id
in: path
required: true
schema:
type: string
get:
operationId: getCandidateDocument
tags: [Documents]
summary: Retrieve a candidate document
responses:
'200':
description: The document.
content:
application/json:
schema:
$ref: '#/components/schemas/Document'
/invitations:
get:
operationId: listInvitations
tags: [Invitations]
summary: List invitations
parameters:
- $ref: '#/components/parameters/Page'
- $ref: '#/components/parameters/PerPage'
- name: status
in: query
schema:
type: string
enum: [pending, completed, expired]
responses:
'200':
description: A paginated list of invitations.
content:
application/json:
schema:
$ref: '#/components/schemas/InvitationList'
post:
operationId: createInvitation
tags: [Invitations]
summary: Create an invitation
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/InvitationCreate'
responses:
'201':
description: The created invitation.
content:
application/json:
schema:
$ref: '#/components/schemas/Invitation'
/invitations/{id}:
parameters:
- $ref: '#/components/parameters/ResourceId'
get:
operationId: getInvitation
tags: [Invitations]
summary: Retrieve an invitation
responses:
'200':
description: The invitation.
content:
application/json:
schema:
$ref: '#/components/schemas/Invitation'
delete:
operationId: cancelInvitation
tags: [Invitations]
summary: Cancel an invitation
responses:
'200':
description: The cancelled invitation.
content:
application/json:
schema:
$ref: '#/components/schemas/Invitation'
/reports:
post:
operationId: createReport
tags: [Reports]
summary: Create a report
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ReportCreate'
responses:
'201':
description: The created report.
content:
application/json:
schema:
$ref: '#/components/schemas/Report'
/reports/{id}:
parameters:
- $ref: '#/components/parameters/ResourceId'
get:
operationId: getReport
tags: [Reports]
summary: Retrieve a report
parameters:
- name: include
in: query
description: Comma-separated related resources to embed (e.g. documents,geos).
schema:
type: string
responses:
'200':
description: The report.
content:
application/json:
schema:
$ref: '#/components/schemas/Report'
post:
operationId: updateReport
tags: [Reports]
summary: Update or upgrade a report
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
package:
type: string
description: A package slug to upgrade the report to.
responses:
'200':
description: The updated report.
content:
application/json:
schema:
$ref: '#/components/schemas/Report'
/reports/{id}/complete:
parameters:
- $ref: '#/components/parameters/ResourceId'
post:
operationId: completeReport
tags: [Reports]
summary: Complete a report
responses:
'200':
description: The completed report.
content:
application/json:
schema:
$ref: '#/components/schemas/Report'
/reports/{id}/eta:
parameters:
- $ref: '#/components/parameters/ResourceId'
get:
operationId: getReportEta
tags: [Reports]
summary: Retrieve a report ETA
responses:
'200':
description: The estimated completion time for the report.
content:
application/json:
schema:
type: object
properties:
estimated_completion_time:
type: string
format: date-time
/reports/{report_id}/ssn_trace/{id}:
parameters:
- name: report_id
in: path
required: true
schema:
type: string
- $ref: '#/components/parameters/ResourceId'
get:
operationId: getSsnTrace
tags: [Screenings]
summary: Retrieve an SSN trace
responses:
'200':
description: The SSN trace screening.
content:
application/json:
schema:
$ref: '#/components/schemas/Screening'
/reports/{report_id}/county_criminal_searches/{id}:
parameters:
- name: report_id
in: path
required: true
schema:
type: string
- $ref: '#/components/parameters/ResourceId'
get:
operationId: getCountyCriminalSearch
tags: [Screenings]
summary: Retrieve a county criminal search
responses:
'200':
description: The county criminal search screening.
content:
application/json:
schema:
$ref: '#/components/schemas/Screening'
/reports/{report_id}/national_criminal_search/{id}:
parameters:
- name: report_id
in: path
required: true
schema:
type: string
- $ref: '#/components/parameters/ResourceId'
get:
operationId: getNationalCriminalSearch
tags: [Screenings]
summary: Retrieve a national criminal search
responses:
'200':
description: The national criminal search screening.
content:
application/json:
schema:
$ref: '#/components/schemas/Screening'
/reports/{report_id}/federal_criminal_search/{id}:
parameters:
- name: report_id
in: path
required: true
schema:
type: string
- $ref: '#/components/parameters/ResourceId'
get:
operationId: getFederalCriminalSearch
tags: [Screenings]
summary: Retrieve a federal criminal search
responses:
'200':
description: The federal criminal search screening.
content:
application/json:
schema:
$ref: '#/components/schemas/Screening'
/reports/{report_id}/sex_offender_search/{id}:
parameters:
- name: report_id
in: path
required: true
schema:
type: string
- $ref: '#/components/parameters/ResourceId'
get:
operationId: getSexOffenderSearch
tags: [Screenings]
summary: Retrieve a sex offender registry search
responses:
'200':
description: The sex offender search screening.
content:
application/json:
schema:
$ref: '#/components/schemas/Screening'
/reports/{report_id}/motor_vehicle_report/{id}:
parameters:
- name: report_id
in: path
required: true
schema:
type: string
- $ref: '#/components/parameters/ResourceId'
get:
operationId: getMotorVehicleReport
tags: [Screenings]
summary: Retrieve a motor vehicle report
responses:
'200':
description: The motor vehicle report screening.
content:
application/json:
schema:
$ref: '#/components/schemas/Screening'
/reports/{report_id}/verifications:
parameters:
- name: report_id
in: path
required: true
schema:
type: string
get:
operationId: listVerifications
tags: [Verifications]
summary: List verifications for a report
responses:
'200':
description: A list of verifications.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Screening'
/reports/{report_id}/verifications/{id}:
parameters:
- name: report_id
in: path
required: true
schema:
type: string
- $ref: '#/components/parameters/ResourceId'
get:
operationId: getVerification
tags: [Verifications]
summary: Retrieve a verification
responses:
'200':
description: The verification screening.
content:
application/json:
schema:
$ref: '#/components/schemas/Screening'
/packages:
get:
operationId: listPackages
tags: [Packages]
summary: List packages
parameters:
- $ref: '#/components/parameters/Page'
- $ref: '#/components/parameters/PerPage'
responses:
'200':
description: A paginated list of packages.
content:
application/json:
schema:
$ref: '#/components/schemas/PackageList'
/packages/{id}:
parameters:
- $ref: '#/components/parameters/ResourceId'
get:
operationId: getPackage
tags: [Packages]
summary: Retrieve a package
responses:
'200':
description: The package.
content:
application/json:
schema:
$ref: '#/components/schemas/Package'
/programs:
get:
operationId: listPrograms
tags: [Packages]
summary: List programs
responses:
'200':
description: A list of programs.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Program'
/programs/{id}:
parameters:
- $ref: '#/components/parameters/ResourceId'
get:
operationId: getProgram
tags: [Packages]
summary: Retrieve a program
responses:
'200':
description: The program.
content:
application/json:
schema:
$ref: '#/components/schemas/Program'
/reports/{id}/adverse_actions:
parameters:
- $ref: '#/components/parameters/ResourceId'
get:
operationId: listAdverseActions
tags: [Adverse Actions]
summary: List adverse actions for a report
responses:
'200':
description: A list of adverse actions.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/AdverseAction'
post:
operationId: createAdverseAction
tags: [Adverse Actions]
summary: Create an adverse action
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
adverse_item_ids:
type: array
items:
type: string
responses:
'201':
description: The created adverse action.
content:
application/json:
schema:
$ref: '#/components/schemas/AdverseAction'
/adverse_actions/{id}:
parameters:
- $ref: '#/components/parameters/ResourceId'
get:
operationId: getAdverseAction
tags: [Adverse Actions]
summary: Retrieve an adverse action
responses:
'200':
description: The adverse action.
content:
application/json:
schema:
$ref: '#/components/schemas/AdverseAction'
delete:
operationId: cancelAdverseAction
tags: [Adverse Actions]
summary: Cancel an adverse action
responses:
'200':
description: The cancelled adverse action.
content:
application/json:
schema:
$ref: '#/components/schemas/AdverseAction'
/subscriptions:
get:
operationId: listSubscriptions
tags: [Subscriptions]
summary: List subscriptions
responses:
'200':
description: A list of subscriptions.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Subscription'
post:
operationId: createSubscription
tags: [Subscriptions]
summary: Create a subscription
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SubscriptionCreate'
responses:
'201':
description: The created subscription.
content:
application/json:
schema:
$ref: '#/components/schemas/Subscription'
/subscriptions/{id}:
parameters:
- $ref: '#/components/parameters/ResourceId'
get:
operationId: getSubscription
tags: [Subscriptions]
summary: Retrieve a subscription
responses:
'200':
description: The subscription.
content:
application/json:
schema:
$ref: '#/components/schemas/Subscription'
post:
operationId: updateSubscription
tags: [Subscriptions]
summary: Update a subscription
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SubscriptionCreate'
responses:
'200':
description: The updated subscription.
content:
application/json:
schema:
$ref: '#/components/schemas/Subscription'
delete:
operationId: cancelSubscription
tags: [Subscriptions]
summary: Cancel a subscription
responses:
'200':
description: The cancelled subscription.
content:
application/json:
schema:
$ref: '#/components/schemas/Subscription'
/continuous_checks:
get:
operationId: listContinuousChecks
tags: [Continuous Checks]
summary: List continuous checks
responses:
'200':
description: A list of continuous checks.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/ContinuousCheck'
post:
operationId: createContinuousCheck
tags: [Continuous Checks]
summary: Create a continuous check
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ContinuousCheckCreate'
responses:
'201':
description: The created continuous check.
content:
application/json:
schema:
$ref: '#/components/schemas/ContinuousCheck'
/continuous_checks/{id}:
parameters:
- $ref: '#/components/parameters/ResourceId'
get:
operationId: getContinuousCheck
tags: [Continuous Checks]
summary: Retrieve a continuous check
responses:
'200':
description: The continuous check.
content:
application/json:
schema:
$ref: '#/components/schemas/ContinuousCheck'
delete:
operationId: cancelContinuousCheck
tags: [Continuous Checks]
summary: Cancel a continuous check
responses:
'200':
description: The cancelled continuous check.
content:
application/json:
schema:
$ref: '#/components/schemas/ContinuousCheck'
/hierarchy:
post:
operationId: createHierarchy
tags: [Nodes and Hierarchy]
summary: Create a hierarchy
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
nodes:
type: array
items:
$ref: '#/components/schemas/Node'
responses:
'200':
description: The hierarchy update status.
content:
application/json:
schema:
type: object
properties:
status:
type: string
/hierarchy/nodes:
post:
operationId: addHierarchyNodes
tags: [Nodes and Hierarchy]
summary: Add nodes to the hierarchy
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
nodes:
type: array
items:
$ref: '#/components/schemas/Node'
responses:
'200':
description: The hierarchy update status.
/hierarchy/status:
get:
operationId: getHierarchyStatus
tags: [Nodes and Hierarchy]
summary: Retrieve hierarchy update status
responses:
'200':
description: The status of the most recent hierarchy update.
content:
application/json:
schema:
type: object
properties:
status:
type: string
/nodes:
get:
operationId: listNodes
tags: [Nodes and Hierarchy]
summary: List nodes
responses:
'200':
description: A list of nodes.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Node'
/nodes/{id}:
parameters:
- $ref: '#/components/parameters/ResourceId'
get:
operationId: getNode
tags: [Nodes and Hierarchy]
summary: Retrieve a node
responses:
'200':
description: The node.
content:
application/json:
schema:
$ref: '#/components/schemas/Node'
patch:
operationId: updateNode
tags: [Nodes and Hierarchy]
summary: Update a node
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Node'
responses:
'200':
description: The updated node.
content:
application/json:
schema:
$ref: '#/components/schemas/Node'
delete:
operationId: deleteNode
tags: [Nodes and Hierarchy]
summary: Delete a node
responses:
'200':
description: The node was deleted.
/geos:
get:
operationId: listGeos
tags: [Geos]
summary: List geos
responses:
'200':
description: A list of geos.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Geo'
post:
operationId: createGeo
tags: [Geos]
summary: Create a geo
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Geo'
responses:
'201':
description: The created geo.
content:
application/json:
schema:
$ref: '#/components/schemas/Geo'
/geos/{id}:
parameters:
- $ref: '#/components/parameters/ResourceId'
get:
operationId: getGeo
tags: [Geos]
summary: Retrieve a geo
responses:
'200':
description: The geo.
content:
application/json:
schema:
$ref: '#/components/schemas/Geo'
post:
operationId: updateGeo
tags: [Geos]
summary: Update a geo
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Geo'
responses:
'200':
description: The updated geo.
content:
application/json:
schema:
$ref: '#/components/schemas/Geo'
delete:
operationId: deleteGeo
tags: [Geos]
summary: Delete a geo
responses:
'200':
description: The geo was deleted.
/webhooks:
get:
operationId: listWebhooks
tags: [Webhooks]
summary: List webhooks
responses:
'200':
description: A list of webhook subscriptions.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Webhook'
post:
operationId: createWebhook
tags: [Webhooks]
summary: Create a webhook
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookCreate'
responses:
'201':
description: The created webhook.
content:
application/json:
schema:
$ref: '#/components/schemas/Webhook'
/webhooks/{id}:
parameters:
- $ref: '#/components/parameters/ResourceId'
get:
operationId: getWebhook
tags: [Webhooks]
summary: Retrieve a webhook
responses:
'200':
description: The webhook.
content:
application/json:
schema:
$ref: '#/components/schemas/Webhook'
delete:
operationId: deleteWebhook
tags: [Webhooks]
summary: Delete a webhook
responses:
'200':
description: The webhook was deleted.
/account:
get:
operationId: getAccount
tags: [Account]
summary: Retrieve account details
responses:
'200':
description: The account.
content:
application/json:
schema:
$ref: '#/components/schemas/Account'
/users:
get:
operationId: listUsers
tags: [Account]
summary: List users
responses:
'200':
description: A list of users on the account.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/User'
components:
securitySchemes:
basicAuth:
type: http
scheme: basic
description: >-
HTTP Basic auth with your secret API key as the username and an empty
password. Checkr Partner integrations authenticate on behalf of
customer accounts using OAuth instead.
parameters:
ResourceId:
name: id
in: path
required: true
description: The unique identifier of the resource.
schema:
type: string
Page:
name: page
in: query
description: The page of results to return.
schema:
type: integer
default: 1
PerPage:
name: per_page
in: query
description: The number of results per page (default 25).
schema:
type: integer
default: 25
maximum: 100
responses:
BadRequest:
description: The request was invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Unauthorized:
description: Authentication failed or was missing.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
NotFound:
description: The resource was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
schemas:
Error:
type: object
properties:
error:
type: string
errors:
type: array
items:
type: string
Candidate:
type: object
properties:
id:
type: string
object:
type: string
example: candidate
first_name:
type: string
middle_name:
type: string
last_name:
type: string
email:
type: string
format: email
phone:
type: string
dob:
type: string
format: date
ssn:
type: string
description: May be returned masked (XXX-XX-1234).
zipcode:
type: string
driver_license_number:
type: string
driver_license_state:
type: string
created_at:
type: string
format: date-time
CandidateCreate:
type: object
required:
- email
properties:
first_name:
type: string
middle_name:
type: string
last_name:
type: string
email:
type: string
format: email
phone:
type: string
dob:
type: string
format: date
ssn:
type: string
zipcode:
type: string
work_locations:
type: array
# --- truncated at 32 KB (41 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/checkr/refs/heads/main/openapi/checkr-openapi.yml