openapi: 3.0.3
info:
title: Sterling API
description: >-
The Sterling API integrates background and identity screening into your
platform and manages the process end to end. It is a RESTful, OAuth2-secured
API: you exchange a Client ID and Client Secret for an access token, then
create candidates, look up the screening packages available to your account,
initiate screenings (orders), invite candidates by email or hosted link,
retrieve results/reports (PDF or HTML), and receive real-time status updates
via webhook callbacks.
ACCESS IS GATED. Credentials are provisioned per screening region (US, EMEA,
Canada, or APAC) by request through Sterling; there is a separate set of
credentials for the sandbox/integration environment and for production.
GROUNDING AND MODELING NOTE: The documented, confirmed operations are the
OAuth token exchange, GET /packages, POST /candidates, POST /screenings
(including the invite object and the callbackUri for webhooks), and the
availability of results/reports with per-item statuses. The remaining
operations in this document (list/retrieve/cancel screenings, retrieve/update
candidates, retrieve a package, report retrieval paths, recurring screening
management, and standalone webhook subscription management) are HONESTLY
MODELED on Sterling's documented order lifecycle and are marked in each
operation description with "[MODELED]". The API request host is also modeled:
exact hosts are provisioned with your credentials. The OAuth host
auth.sterlingcheck.app and the documentation host apidocs.sterlingcheck.app
are confirmed; api.sterlingcheck.app is a representative modeled base.
Sterling is a First Advantage company (First Advantage completed its $2.2B
acquisition of Sterling Check Corp on October 31, 2024).
version: '2.0'
contact:
name: Sterling (a First Advantage company)
url: https://www.sterlingcheck.com/services/api/
x-documentation: https://apidocs.sterlingcheck.app/
x-developer-portal: https://developer.sterlingcheck.app/
x-acquisition: First Advantage completed acquisition of Sterling Check Corp on 2024-10-31 ($2.2B).
servers:
- url: https://api.sterlingcheck.app/v2
description: Production (MODELED representative host - exact host provisioned with production credentials)
- url: https://api-sandbox.sterlingcheck.app/v2
description: Sandbox / Integration (MODELED representative host - exact host provisioned with sandbox credentials)
security:
- oAuth2ClientCredentials: []
- bearerAuth: []
tags:
- name: Authentication
description: OAuth2 token exchange using your Client ID and Client Secret.
- name: Packages
description: Screening packages (groups of screening products) available to your account.
- name: Candidates
description: Candidate (subject) records that screenings are run against.
- name: Screenings
description: Screening orders and their lifecycle, including recurring/continuous screening.
- name: Invites
description: Candidate invitations to complete consent and data collection.
- name: Reports
description: Results of completed screenings, with per-item statuses (PDF or HTML).
- name: Webhooks
description: Real-time screening status callbacks.
paths:
/oauth/token:
servers:
- url: https://auth.sterlingcheck.app
description: OAuth token host (CONFIRMED domain)
post:
operationId: createAccessToken
tags:
- Authentication
summary: Exchange Client ID and Client Secret for an access token
description: >-
[CONFIRMED] Send your Client ID and Client Secret to obtain an OAuth2
access token. The response contains an access token used as a Bearer
token on all subsequent requests. Credentials are region-scoped (US,
EMEA, Canada, APAC) and differ between sandbox and production.
security: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- client_id
- client_secret
- grant_type
properties:
client_id:
type: string
client_secret:
type: string
grant_type:
type: string
enum: [client_credentials]
default: client_credentials
responses:
'200':
description: An access token.
content:
application/json:
schema:
type: object
properties:
access_token:
type: string
token_type:
type: string
example: Bearer
expires_in:
type: integer
example: 3600
'401':
$ref: '#/components/responses/Unauthorized'
/packages:
get:
operationId: listPackages
tags:
- Packages
summary: List available screening packages
description: >-
[CONFIRMED] Retrieve a list of the packages available to your account. A
package is a group of screening products. Each package specifies which
fields are required on a candidate record in order to process the
associated screening.
responses:
'200':
description: A list of packages.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Package'
'401':
$ref: '#/components/responses/Unauthorized'
/packages/{packageId}:
get:
operationId: getPackage
tags:
- Packages
summary: Retrieve a package
description: >-
[MODELED] Retrieve a single package by ID, including the screening
products it contains and the candidate fields it requires.
parameters:
- $ref: '#/components/parameters/PackageId'
responses:
'200':
description: A package.
content:
application/json:
schema:
$ref: '#/components/schemas/Package'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/candidates:
post:
operationId: createCandidate
tags:
- Candidates
summary: Create a candidate
description: >-
[CONFIRMED] Create a candidate (the subject of a screening). Minimum
fields are first name, last name, email, and clientReferenceId.
Additional PII (date of birth, address history, government IDs, etc.) may
be required depending on the package the candidate will be screened with.
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/{candidateId}:
get:
operationId: getCandidate
tags:
- Candidates
summary: Retrieve a candidate
description: '[MODELED] Retrieve a candidate record by ID.'
parameters:
- $ref: '#/components/parameters/CandidateId'
responses:
'200':
description: A candidate.
content:
application/json:
schema:
$ref: '#/components/schemas/Candidate'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
patch:
operationId: updateCandidate
tags:
- Candidates
summary: Update a candidate
description: >-
[MODELED] Update mutable fields on a candidate record before a screening
is submitted.
parameters:
- $ref: '#/components/parameters/CandidateId'
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'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/screenings:
get:
operationId: listScreenings
tags:
- Screenings
summary: List screenings
description: '[MODELED] List the screenings (orders) in your account, filterable by status.'
parameters:
- name: status
in: query
required: false
schema:
$ref: '#/components/schemas/ScreeningStatus'
- name: limit
in: query
required: false
schema:
type: integer
default: 25
- name: offset
in: query
required: false
schema:
type: integer
default: 0
responses:
'200':
description: A list of screenings.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Screening'
'401':
$ref: '#/components/responses/Unauthorized'
post:
operationId: createScreening
tags:
- Screenings
summary: Initiate a screening
description: >-
[CONFIRMED] Initiate a background screening (order) for a candidate
against a package. Three initiation workflows are supported via the
invite object: set invite.method to "email" so Sterling emails the
candidate an invite; set invite.method to "link" to receive a hosted form
URL in the response for embedding in your own flow; or omit the invite to
initiate directly when candidate data is already complete. Provide a
callbackUri to receive real-time webhook status updates. Set the recurring
object to schedule continuous/recurring screening.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ScreeningCreate'
responses:
'201':
description: The created screening. If invite.method is "link", the response includes the hosted form URL.
content:
application/json:
schema:
$ref: '#/components/schemas/Screening'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
/screenings/{screeningId}:
get:
operationId: getScreening
tags:
- Screenings
summary: Retrieve a screening
description: >-
[MODELED] Retrieve a screening (order) by ID, including its current
status and rolled-up report item statuses.
parameters:
- $ref: '#/components/parameters/ScreeningId'
responses:
'200':
description: A screening.
content:
application/json:
schema:
$ref: '#/components/schemas/Screening'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/screenings/{screeningId}/cancel:
post:
operationId: cancelScreening
tags:
- Screenings
summary: Cancel a screening
description: '[MODELED] Cancel an in-progress screening where allowed by product and compliance rules.'
parameters:
- $ref: '#/components/parameters/ScreeningId'
responses:
'200':
description: The cancelled screening.
content:
application/json:
schema:
$ref: '#/components/schemas/Screening'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/screenings/{screeningId}/invite:
post:
operationId: resendInvite
tags:
- Invites
summary: Resend or retrieve a screening invite
description: >-
[MODELED] Resend the candidate invitation email, or retrieve the hosted
invite/form link for a screening that was created with invite.method set
to "link".
parameters:
- $ref: '#/components/parameters/ScreeningId'
responses:
'200':
description: The invite details, including the hosted form URL.
content:
application/json:
schema:
$ref: '#/components/schemas/Invite'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/screenings/{screeningId}/report:
get:
operationId: getScreeningReport
tags:
- Reports
summary: Retrieve a screening report
description: >-
[MODELED path, CONFIRMED concept] Retrieve the report/results for a
completed screening. A screening rolls up multiple report items, each
with its own status. Request PDF or HTML via the Accept header (the docs
state reports are available in PDF or HTML formats).
parameters:
- $ref: '#/components/parameters/ScreeningId'
- name: Accept
in: header
required: false
schema:
type: string
enum:
- application/json
- application/pdf
- text/html
default: application/json
responses:
'200':
description: The screening report.
content:
application/json:
schema:
$ref: '#/components/schemas/Report'
application/pdf:
schema:
type: string
format: binary
text/html:
schema:
type: string
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/webhooks:
get:
operationId: listWebhooks
tags:
- Webhooks
summary: List webhook subscriptions
description: >-
[MODELED] List account-level webhook subscriptions. The confirmed
mechanism is the per-screening callbackUri on POST /screenings; an
account-level subscription surface is modeled here.
responses:
'200':
description: A list of webhook subscriptions.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/WebhookSubscription'
'401':
$ref: '#/components/responses/Unauthorized'
post:
operationId: createWebhook
tags:
- Webhooks
summary: Create a webhook subscription
description: '[MODELED] Register an account-level callback URL to receive screening status events.'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookSubscriptionCreate'
responses:
'201':
description: The created webhook subscription.
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookSubscription'
'401':
$ref: '#/components/responses/Unauthorized'
/webhooks/{webhookId}:
delete:
operationId: deleteWebhook
tags:
- Webhooks
summary: Delete a webhook subscription
description: '[MODELED] Delete an account-level webhook subscription.'
parameters:
- name: webhookId
in: path
required: true
schema:
type: string
responses:
'204':
description: Deleted.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
components:
securitySchemes:
oAuth2ClientCredentials:
type: oauth2
description: OAuth2 client credentials grant using your Client ID and Client Secret.
flows:
clientCredentials:
tokenUrl: https://auth.sterlingcheck.app/oauth/token
scopes: {}
bearerAuth:
type: http
scheme: bearer
description: The access token returned from the OAuth token exchange, sent as a Bearer token.
parameters:
PackageId:
name: packageId
in: path
required: true
schema:
type: string
CandidateId:
name: candidateId
in: path
required: true
schema:
type: string
ScreeningId:
name: screeningId
in: path
required: true
schema:
type: string
responses:
BadRequest:
description: The request was malformed or missing required fields.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Unauthorized:
description: Missing or invalid access token.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
NotFound:
description: The requested resource was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
schemas:
Package:
type: object
properties:
id:
type: string
name:
type: string
description:
type: string
screeningProducts:
type: array
items:
type: string
description: The screening products grouped into this package (e.g., criminal, employment verification, drug test).
requiredCandidateFields:
type: array
items:
type: string
description: Candidate fields required to process a screening with this package.
CandidateCreate:
type: object
required:
- firstName
- lastName
- email
- clientReferenceId
properties:
firstName:
type: string
lastName:
type: string
middleName:
type: string
email:
type: string
format: email
clientReferenceId:
type: string
description: Your own reference identifier for the candidate.
phone:
type: string
dateOfBirth:
type: string
format: date
addresses:
type: array
items:
$ref: '#/components/schemas/Address'
Candidate:
allOf:
- $ref: '#/components/schemas/CandidateCreate'
- type: object
properties:
id:
type: string
createdAt:
type: string
format: date-time
Address:
type: object
properties:
line1:
type: string
line2:
type: string
city:
type: string
region:
type: string
postalCode:
type: string
country:
type: string
ScreeningCreate:
type: object
required:
- candidateId
- packageId
properties:
candidateId:
type: string
packageId:
type: string
clientReferenceId:
type: string
callbackUri:
type: string
format: uri
description: URL Sterling posts real-time status-change webhook events to.
invite:
$ref: '#/components/schemas/InviteRequest'
recurring:
$ref: '#/components/schemas/RecurringConfig'
InviteRequest:
type: object
properties:
method:
type: string
enum: [email, link]
description: >-
"email" sends the candidate an invitation email; "link" returns a
hosted form URL in the response for you to embed.
RecurringConfig:
type: object
description: '[MODELED] Configure continuous/recurring screening to monitor a candidate over time.'
properties:
enabled:
type: boolean
interval:
type: string
enum: [monthly, quarterly, annually]
Screening:
type: object
properties:
id:
type: string
candidateId:
type: string
packageId:
type: string
clientReferenceId:
type: string
status:
$ref: '#/components/schemas/ScreeningStatus'
inviteUrl:
type: string
format: uri
description: Present when invite.method was "link".
callbackUri:
type: string
format: uri
reportItems:
type: array
items:
$ref: '#/components/schemas/ReportItem'
createdAt:
type: string
format: date-time
completedAt:
type: string
format: date-time
ScreeningStatus:
type: string
description: Rolled-up screening status. Individual report items carry their own statuses.
enum:
- pending
- awaiting_candidate
- in_progress
- completed
- cancelled
- review
Invite:
type: object
properties:
screeningId:
type: string
method:
type: string
enum: [email, link]
url:
type: string
format: uri
sentAt:
type: string
format: date-time
Report:
type: object
properties:
screeningId:
type: string
status:
$ref: '#/components/schemas/ScreeningStatus'
items:
type: array
items:
$ref: '#/components/schemas/ReportItem'
completedAt:
type: string
format: date-time
ReportItem:
type: object
description: An individual product result within a screening report, each with its own status.
properties:
product:
type: string
status:
type: string
description: Common report item status values (e.g., pending, clear, consider, review).
summary:
type: string
WebhookSubscription:
type: object
properties:
id:
type: string
callbackUri:
type: string
format: uri
events:
type: array
items:
type: string
active:
type: boolean
WebhookSubscriptionCreate:
type: object
required:
- callbackUri
properties:
callbackUri:
type: string
format: uri
events:
type: array
items:
type: string
Error:
type: object
properties:
code:
type: string
message:
type: string