Checkr is a modern, RESTful API-driven background screening service. The Checkr API uses resource-oriented URLs, supports HTTPS authentication and HTTPS verbs, and leverages JSON in all responses passed back to customers.
Checkr is used by over 10,000 customers in a wide variety of industries, and supports a range of screening products and candidate workflows. For a full list of our screenings, please see the Checkr Screenings section below or read the Checkr Help Center articles on Screening Types.
This Programming Guide is designed to help customers get up-and-running with Checkr's background screening services, both by providing the necessary context to understand the background screening industry and its regulations, and by giving technical guidance on how to work with the Checkr API.
Note: The cURL command is used for all examples in the Checkr API documentation.
For a complete set of User Guides for the Checkr Dashboard, and more information on the compliance and regulatory aspects of background screenings, please see the Checkr Help Center.
For a more targeted set of Checkr Dashboard learning paths for talent sourcing roles like Recruiters, Adjudicators, or Program Administrators, please see the Checkr Learning Center.
Checkr is a modern, RESTful API-driven background screening service. The Checkr API uses resource-oriented URLs, supports HTTPS authentication and HTTPS verbs, and leverages JSON in all responses passed back to customers.
Checkr is used by over 10,000 customers in a wide variety of industries, and supports a range of screening products and candidate workflows. For a full list of our screenings, please see the Checkr Screenings section below or read the Checkr Help Center articles on Screening Types.
This Programming Guide is designed to help customers get up-and-running with Checkr's background screening services, both by providing the necessary context to understand the background screening industry and its regulations, and by giving technical guidance on how to work with the Checkr API.
Note: The cURL command is used for all examples in the Checkr API documentation.
For a complete set of User Guides for the Checkr Dashboard, and more information on the compliance and regulatory aspects of background screenings, please see the Checkr Help Center.
For a more targeted set of Checkr Dashboard learning paths for talent sourcing roles like Recruiters, Adjudicators, or Program Administrators, please see the Checkr Learning Center.
Checkr follows a standardized screening process:
To initiate a background check, a customer provides Checkr their candidate's email address (for a Checkr-Hosted Apply Flow) or the candidate's PII (for a self-hosted flow). For more information on ways to achieve this, please see Designing your workflow.
Under the U.S. Fair Credit Reporting Act (FCRA), customers are obligated to collect consent from their candidates when running background checks through Checkr or any other Consumer Reporting Agency (CRA).
The Checkr-Hosted Apply Flow presents candidates with fields in which the requested PII may be entered, and collects candidate information on behalf of the customer. Checkr will also present disclosures and authorizations to the candidate, and enable eSignature to capture consent, on behalf of customers using this flow with the Checkr Dashboard or email invitation flow.
Custom self-hosted flows collect candidate PII, and pass the information to Checkr using the Checkr API. Customers creating a self-hosted flow will receive guidance from the Checkr team on setting up a similar process as required.
Checkr runs an SSN Trace to match the candidate’s provided PII with existing credit header data mapped to the SSN. This process yields a list of names and addresses associated with the entered SSN, which can be used to supplement the background check process.
At this point Checkr also conducts some initial data comparisons to check that critical pieces of information, like a candidate's submitted Date of Birth (DOB) and SSN, align with information held on file by the credit bureaus. If there is information that looks out of place, Checkr may reach out directly to the candidate, through their email address, to gain further confirmation or data from the individual.
Once the candidate's information has been confirmed and an address history developed, the background check screening process begins.
Checkr then runs the customer's requested Screenings. Based on the results of the SSN Trace, Checkr may expand the search for the requested Screenings to include counties where the candidate may have lived in the past.
Once a report has been completed, customers receive a report assessment update of Clear or Consider through their selected method of API webhooks, email, or Checkr Dashboard notifications.
Clear and Consider are the default assessments. A Clear assessment can be interpreted as that report having no items listed on the candidate’s record that require consideration. A report with an assessment of Consider indicates that there are items on the candidate’s report that require your review. With both Clear and Consider reports, customers must decide whether or not to engage a candidate. Checkr does not make this determination on the customer’s behalf.
After the Report is completed and returned, the customer must evaluate the report, and make a final hiring determination. In maintaining a process compliant with per FCRA legislation and EEOC guidelines, Checkr does not make this determination on the customer's behalf.
Before gaining a Checkr test or production account, you must first work with a Checkr Account Executive or Customer Success representative to create and credential your account.
The background screening industry in the United States is heavily regulated by federal, state, and local levels of government, and primarily by the Fair Credit Reporting Act (FCRA). Checkr complies with these laws, and helps its customers comply, through multiple Checkr product features.
Two key processes in the account authorization process also enable compliance: establishing permissible purpose, and confirming a compliant user interface workflow.
One of the main provisions of FCRA is the requirement to establish a legitimate "permissible purpose" for running a background screen on an individual. These permissible purposes include running background screens for employment purposes (that is, making hiring decisions), making a decision to extend credit to an individual, or for what the law calls a "legitimate business purpose".
Checkr establishes a customer's permissible purpose by collecting and confirming a number of key details about the business entity running a background screen, including:
Some permissible purposes may impose additional legal requirements on the business entity running a background screen. For example, purposes involving checking a candidate's credit history require an onsite inspection of the entity's business premises.
When building a candidate user experience that includes the capture of information necessary to run a background check, there are a number of essential components that must be included to send a compliant request to Checkr. For more information on these requirements and best practices, please see Building your candidate experience.
Before a Checkr account is credentialed and authorized for production API access, the Checkr Customer Success team confirms that your UI/UX flow meets our requirements and that all necessary information is being appropriately captured. More details about these requirements are included below and throughout the Checkr customer account onboarding process.
Checkr authenticates your API requests using your account's API keys. If you do not include your key when making an API request, Checkr will return an authentication error.
Go to Account Settings > Developer Settings in the Checkr Dashboard to create both Secret and Publishable keys for your account. Use the Secret Key within your staging and production environments.
Resources like Candidates, Reports, and Packages will not transfer from your Staging environment to your Live environment. For more information, please see Staging Account below.
There are two types of API keys: secret and publishable.
Once your Checkr account has been created, your API keys will be available in the Checkr Dashboard, in the Account Settings > Developer Settings page.
Note: To prevent unexpected charges for production background checks, do not use your production Publishable API key for testing or development.
Keeping your keys safe
Access to your API keys should be granted only to those that need them. Your secret API key can be used to make any API call on behalf of your account, such as creating Candidates, requesting and upgrading Screenings, and creating Geos. Your publishable API key can only create Candidates in the Checkr system, and may be used to publish app or site builds.
To further protect your keys, ensure that they are not included in any version control system that you may be using.
Expiring keys
If an API key is compromised, expire the key in the Checkr Dashboard to block it. Click Expire key to set an expiration date for the selected key, and Create new key to create a new one to replace it.
Checkr's API is flexible enough to support a range of workflows for integrating background screening into your candidate onboarding process. At a high-level there are three options, each with unique benefits and disadvantages.
Option | Benefits | Disadvantages |
---|---|---|
Checkr Dashboard experience |
|
|
Checkr-hosted candidate experience |
|
|
Self-hosted candidate experience |
|
|
The Checkr Dashboard allows customers to initiate a background check through either the Checkr-Hosted Apply Flow or through a Manual flow.
Selecting Invite Candidates allows customers to enter an email address for their candidates. Checkr will then issue an invitation to the selected candidate which includes a Checkr-provided link. Clicking the link launches the Checkr-Hosted Apply Flow, which will walk them through the next steps in the process.
Selecting Manual Order requires customers to enter their candidate's PII, and confirm that they have collected the necessary authorizations on their candidate's behalf.
For more information, see Order a Report in the Checkr Help Center.
The Checkr-hosted candidate experience enables Checkr customers to easily set up a modern, compliant candidate background screening process in their onboarding flow with limited development effort. The Checkr-hosted candidate experience has the full set of features and functionality of the Checkr product, and is built on top of the Checkr API, making it an easy and powerful option for customers looking to begin using Checkr as quickly as possible.
The Checkr-Hosted Apply Flow, by which invitations are issued to candidates to participate in their background check, forms the basis of the Checkr-hosted candidate experience. Use the Invitations resource to build this automated process into your application.
The Checkr-hosted experience can be initiated in two ways:
Candidate invitations triggered by API: Customers can choose to build a programmatic trigger into their site or product to order reports and send candidates invitations to participate in the background check process. In this case, a customer passes Checkr a candidate email address through the API, which triggers an email to that address to collect the candidate's information and present the necessary compliance forms and disclosures. This option requires developer time to build a Checkr backend integration into the customer's product, but does present benefits for automation and programmatic ordering.
Candidate invitations triggered through the Checkr Dashboard: Customers can log into the Checkr Dashboard and issue an invitation to participate in the background check process to a candidate's email address. This option requires no developer time to build any Checkr integration, but lacks any automation or programmatic ordering, making it difficult to scale for high volume environments.
Customers may also use the Checkr Dashboard to submit a Manual Order. Selecting this option requires them to collect the candidate’s authorization and consent to a background screening “offline”. This means that the customer will collect the candidate’s Personally Identifiable Information (PII), present the necessary authorizations and disclosures, and collect and store necessary signatures through separate means. Customers must then submit their candidate's PII to Checkr through the Checkr Dashboard, and certify that proper consent was obtained from their candidate.
Note: When using candidate invitations and the Checkr-Hosted Apply Flow, understand that Checkr is facilitating your obligations with regard to applicable consumer reporting laws. Before using either method of candidate invitations, you should fully review the template copies of disclosure(s) and authorization language to ensure your business needs are met.
The self-hosted candidate experience enables Checkr customers to completely control the user onboarding experience, from the look and feel of the candidate's UX, to the specific API calls made during the process, to the flexibility in timing and ordering of those calls. Some unique Checkr functionality, like programmatic report upgrades, are also available only to those customers hosting their own candidate experience.
While hosting your own candidate onboarding experience takes more developer time, it might not be as much time as you think. We've seen teams successfully deploy a new background check and onboarding flow in a single 2-week development sprint.
Building your candidate experience
To help customers meet the regulatory demands of the background screening industry, Checkr has defined the following UX requirements for customers building their own candidate onboarding experience:
Checkr can provide you with copy templates for each of these documents. Checkr routinely has these documents reviewed for general compliance and best practice in the industry, but you should always consult your own legal counsel when using templates and ensure they work for your business. Please work with your Checkr Account Executive or Customer Success Manager to receive Checkr’s set of templates. These templates, the documents they include, and other requirements will be explained throughout the Checkr customer account onboarding process.
Note: Requirements differ for customers running background screening programs limited to running a Motor Vehicle Record (MVR) on candidates for a non-employment or contractor purpose. The requirements for running an MVR in order to provide a service such as a car or scooter rental are far less onerous than the requirements for other uses of the MVR, and require only one or two screens of necessary consent and disclosure. Please contact your Checkr Account Executive or Customer Success Manager if you'd like to learn more about these streamlined requirements.
Compliance and eSignature
Collecting proof of authorization from your candidates is one of your most important responsibilities before performing a background screen through Checkr or any other Consumer Reporting Agency. Under the FCRA, Checkr cannot provide you with a report unless you certify that you have obtained proper authorization. Maintaining proof of this process is essential in the event that either you or Checkr is audited, or a candidate threatens you with litigation.
Checkr recommends two means of collecting and storing this eSignature during the consent and authorization flow:
The Checkr Dashboard allows Checkr customers to begin using the Checkr platform immediately and with no developer effort. The Checkr Dashboard includes the full feature and functionality set as the Checkr API interface, with a few key limitations.
For more information, please see the Checkr Dashboard User Guide in the Checkr Help Center.
The following sections will walk you through the steps necessary to get started running background checks with the Checkr API:
Before gaining access to the Checkr APIs and Dashboard, you must be properly credentialed to request background checks. Work with your Customer Support Representative to provide the required documentation, and complete the credentialing process.
For more information, see Getting credentialed above.
Once you have access set up to log into Checkr, go to Developer Settings in the Checkr Dashboard. Click Create Key > Secret to generate a new Secret Key for your staging environment.
Your production API key is also available from this Developer Settings page. Note that your production key will not be enabled for Reports until you contact clients@checkr.com and request that your account be enabled for live requests.
For more information on using Checkr's Staging environment, see the Staging Accounts section below.
Checkr provides support for several API clients, allowing you to explore the Checkr APIs. Download and install Postman or Insomnia, then click the buttons below to install the Checkr APIs. Or use our OAS3 API spec to work with the tooling of your choice.
Configure your API client using the API key from the Developer Settings page in your Checkr Dashboard. Then use your local client to execute any Checkr API requests. We provide sample parameters and payloads throughout these developer guides to help you in your journey.
Note: Checkr APIs are updated frequently. Use your selected method to reimport our APIs to evaluate our most recent versions.
Checkr API host URLs:
$ curl https://api.checkr.com \
-u YOUR_SECRET_API_KEY:
Use HTTP Basic authentication to authenticate with Checkr, with your API key as the username and an empty password. When using curl
, use the -u
option to specify your API key. (Note the colon following the API key in the examples. It tells cURL to send an empty password.)
Note that staging environment requests are free and return fake data. Once you are production-ready, please email clients@checkr.com and we will enable live requests.
$ curl -X POST https://api.checkr.com/v1/candidates \
-u [YOUR_API_KEY]: \
-d first_name=Michael \
-d middle_name=Gary \
-d last_name=Scott \
-d email=michael.scott@dundermifflin.com \
-d phone=2035408926 \
-d zipcode=06831 \
-d dob=1964-03-15 \
-d ssn=111-11-2001 \
-d driver_license_number=981736076 \
-d driver_license_state=CT \
-d copy_requested=true \
-d 'work_locations[][country]=US'
Create a Candidate by passing the required PII to Checkr.
Remember to replace "YOUR_SECRET_API_KEY"
with your Secret API key in the cURL example on the right.
See Candidates for more details on creating Candidates.
Notes:
copy_requested
boolean captures whether or not the candidate has requested a copy of their background check upon completion. If true
, Checkr will automatically send a copy of the background check to the passed email address on your behalf.email
. We recommend that the candidate's phone number also be provided when creating the Candidate object, as it will be required to authenticate the candidate when they log into the Candidate Portal.first_name
, middle_name
or no_middle_name
, last_name
, and dob
.ssn
and zipcode
are required attributes.driver_license_number
and driver_license_state
.{
"id":"551564b7865af96a28b13f36",
"object":"candidate",
"uri":"/v1/candidates/551564b7865af96a28b13f36",
"created_at":"2018-08-17T01:08:18Z",
"first_name":"Michael",
"last_name":"Scott",
"middle_name":"Gary",
"mother_maiden_name":null,
"dob":"1964-03-15",
"ssn":"XXX-XX-2001",
"email":"michael.scott@dundermifflin.com",
"zipcode":"06831",
"phone":"2035408926",
"driver_license_state":"CT",
"driver_license_number":"981736076",
"copy_requested":true,
"previous_driver_license_state":null,
"previous_driver_license_number":null,
"adjudication":null,
"custom_id":null,
"no_middle_name":false,
"report_ids":[],
"geo_ids":[]
}
Checkr responds immediately with the resulting Candidate object, which includes the ID of the Candidate and a URI that points to the new Candidate object. Store the ID for this new Candidate object, which you'll need when creating a Report in the next step.
$ curl -X POST https://api.checkr.com/v1/invitations \
-u [YOUR_API_KEY]: \
-d candidate_id=551564b7865af96a28b13f36 \
-d package=dunder_mifflin_executive \
-d node=CHLD_e7c3ab7bf4ad \ // only if nodes exist on the account
-d work_locations[][state]=CA \ // state required, city optional
-d work_locations[][city]=San+Francisco
Use the Invitations resource to order a background check using the Checkr-Hosted Apply Flow. Checkr will send an email to the candidate, inviting them to provide their information and consent. Once the invitation is completed a Report is automatically created. The invitation is valid for 7 days, during which Checkr will send a follow-up notice every 24 hours, reminding the candidate to complete their invitation. If 7 days pass and the candidate has not yet completed the invitation, the invitation will expire and you must create a new invitation to proceed with the candidate.
Parameters required to Create an invitation:
candidate_id
: the ID of the candidate for whom the Invitation is created.package
: the Package to use for the background check.work_locations
: the candidate's work location, described using country, state, and city. (ISO-3166 alpha-2 format country code, two letter state code, and the name of the city)node
(optional): the custom_id
of the node associated with the background check. Required if any nodes exist on the account.The work_location
parameter is used by Checkr to determine compliance requirements for background check reports ordered through the Checkr Hosted Apply Flow. Checkr uses the candidate work location to apply the appropriate state- and city-based fair hiring laws, disclosures, and adverse action procedures. If a city is not provided, Checkr uses the state-based regulation.
{
"id": "551564b7865af96a28b13f36",
"object": "invitation",
"uri": "/v1/invitations/551564b7865af96a28b13f36",
"invitation_url":
"https://apply.checkr.com/invite/try-checkr/290f9d6d6e46/test",
"status": "pending",
"created_at": "2015-05-14T17:45:34Z",
"expires_at": "2015-05-21T17:45:34Z",
"completed_at": null,
"deleted_at": null,
"package": "dunder_mifflin_executive",
"candidate_id": "551564b7865af96a28b13f36",
"report_id": null
"tags": []
}
Use the Checkr Candidate ID you have retrieved from Create a Candidate, the Package “slug” (as selected in step Selecting Packages), and the candidate’s work location to create an Invitation.
Note: Checkr requires Candidates to provide only information that is required for the screenings contained in the Package (such as SSN for criminal screenings, driver license number and state for MVR).
Store the resulting Report ID and any of the requested Screening IDs. The ID for this new Report object is required to retrieve the Report. (Checkr will return IDs for all Screenings included in the requested Package. All other Screening IDs will be returned null
.)
{
"id": "507f1f77bcf86cd799439011",
"object": "event",
"type": "report.completed",
"created_at": "2014-01-18T12:34:00Z",
"data": {
"object": {
"id": "4722c07dd9a10c3985ae432a",
"object": "report",
"uri": "/v1/reports/532e71cfe88a1d4e8d00000d",
"created_at": "2014-01-18T12:34:00Z",
"received_at": "2014-01-18T12:34:00Z",
"status": "complete",
"result": "clear",
"package": "driver_pro",
"source": "api",
"candidate_id": "e44aa283528e6fde7d542194",
"ssn_trace_id": "539fd88c101897f7cd000001",
"sex_offender_search_id": "539fd88c101897f7cd000008",
"national_criminal_search_id": "539fd88c101897f7cd000006",
"county_criminal_search_ids": [
"539fdcf335644a0ef4000001",
"532e71cfe88a1d4e8d00000c"
],
"state_criminal_search_ids": [
"539fdcf335644a0ef4000003",
"532e71cfe88a1d4e8d000004"
],
"motor_vehicle_report_id": "539fd88c101897f7cd000007"
}
},
"account_id": "8e122cc56b8fa82d33c6118a"
}
If webhooks are enabled, Checkr pushes a status change webhook event to the customer account's webhook URL with the structure shown in the Test Webhook Response to the right.
Use the resulting Report status (or other data elements) to execute subsequent workflows in your application or program.
$ curl -X GET https://api.checkr.com/v1/reports/a13f4827d8711ddc75abc56ct
Retrieve the results of a report by performing a GET request to the specific URL of the report. For example, executing the command to the right retrieves the Report object below it.
Retrieve the Report created in the previous step by using your Secret API key and Report ID into the cURL command shown to the right.
{
"id": "a13f4827d8711ddc75abc56ct",
"object": "report",
"uri": "/v1/reports/a13f4827d8711ddc75abc56ct",
"status": "complete",
"result": "clear",
"created_at": "2018-08-17T01:10:21Z",
"completed_at": "2018-08-17T01:12:26Z",
"revised_at": null,
"upgraded_at": null,
"turnaround_time": 52,
"package": "dunder_mifflin_executive",
"tags": [],
"adjudication": null,
"assessment": null,
"source": "api",
"candidate_id": "551564b7865af96a28b13f36",
"county_criminal_search_ids": [],
"municipal_criminal_search_ids": [],
"document_ids": [],
"federal_criminal_search_id": "5b64c62b67abb4002d3ec763",
"global_watchlist_search_id": "5b64c5cf67abb400353ec6f7",
"national_criminal_search_id": "5b64c5cf67abb400353ec6f5",
"personal_reference_verification_ids": [],
"professional_reference_verification_ids": [],
"sex_offender_search_id": "5b64c5cf67abb400353ec6f6",
"ssn_trace_id": "5b64c5cf67abb400353ec6f3",
"state_criminal_search_ids": [],
"terrorist_watchlist_search_id": "5b64c5cf67abb400353ec6f7",
"facis_search_id": null,
"arrest_search_id": null,
"motor_vehicle_report_id": null,
"self_disclosure_ids": []
}
Note that the Report is now a full Report with a status of clear
, indicating that no violations or criminal background have come up for this Report.
See Embedding Resources if you wish to embed the full contents of individual screenings (SSN Trace, Sex Offender Registry Search, Global Watchlist Search) in the server response. You can also retrieve those resources using the IDs provided in the server response.
Webhook responses and completed Reports both contain the same information about the results of a criminal screening: the status
of the report which can be complete
, the result
of the report which can be null
, clear
, or consider
, and the assessment of the report, which can be null
, eligible
, review
, or escalated
.
A completed report with result of clear
can be interpreted as that report having no items listed on the candidate's record that must be reviewed. A result of consider
indicates that there are items on the candidate's record that may require consideration.
A report contains an assessment
if the account has Assess enabled. The assessment is returned as eligible
, review
, or escalated
, according to the customer rules defined in Assess. For more information, see Assess in the Checkr User Guides.
In maintaining a compliant process as per FCRA legislation and EEOC guidelines, Checkr does not make any eligibility or hiring decisions (adjudicate) on our customers' behalf.
Checkr provides customers with the option of a “staging account” that can be used to test your integration and use the Checkr Dashboard prior to deploying your integration to your production account. The staging account can be set up to match the settings from your production account and allows for submission of background check orders without incurring any billable events. To accomplish this, Checkr uses candidate “mocked” data setups that result in predefined background check results, mimicking the most common outcomes you will encounter in your production account.
Once your staging account has been created, Checkr will provide you with a document containing this mocked candidate data.
Use our Submit a request form to request a staging account. Enter the following information:
How can we help?: select "I need assistance configuring my account", then select "Other".
Topic: enter "Staging account setup request"
Description: Please enter the following information:
Admin user for staging: Provide the email address to be used as the initial Admin account for this requested staging account.
Checkr production Admin: Provide the email address for one of the Admin users of your Checkr Dashboard account.
New staging accounts are typically created within 1-2 business days of a submitted request.
Upon successful creation of the staging account, the email address specified in the staging account request submission will receive an email from Checkr providing a temporary password to the account and allowing the recipient to create a permanent password. This initial user will have an Admin user role which allows them to invite other users to the account as they see fit.
Once you have Admin access to the staging account, confirm you are using the “Live” mode (do NOT use “Test” mode). Then go to Account Settings > Developer Settings. On this page, in the “API keys” section click Create Key and choose Secret. Use the resulting API key to authenticate all of your API calls to this staging account.
To enable webhooks for the account, from the Account Settings > Developer Settings page scroll down to New Webhook. Enter a URL, select Live, and click Add to create a new webhook. You may also use this page to select the webhook notifications you wish to receive from Checkr.
The staging account’s API calls, responses, and webhooks follow the same pattern and response structure as those of the production environment.
Note: The staging account uses the API host URL: https://api.checkr-staging.com/v1 for all calls.
To facilitate building with the Checkr API, Checkr staging accounts support a number of mocked candidate profiles that will return predictable results. This allows you to test a number of different report outcomes and other workflows before moving your integration to your production account. To ensure the desired outcome, you must enter the candidate data exactly as provided in this mocked candidate data document or the resulting report will remain in pending
status indefinitely.
Reports created in the staging account will typically complete within minutes of submission, though this can vary depending upon the relative load on the staging environment servers.
Note: Checkr’s product and development teams also use the staging environment to test new functionality. It is therefore possible that one or more of the mocked candidate records may not return the expected results. If you encounter unexpected returns for a mock data candidate, please test a different candidate from the mocked data document with a similar predefined outcome. If the problem persists, reach out to your Checkr Customer Support Manager to troubleshoot the issue.
The staging account is built to mimic the production environment and allow developers to build without running production background screenings and incurring a charge. Staging account uses mocked candidate data, and does not support the following functionality available in the production environment:
Please reach out to your Checkr Account Executive or Customer Success Manager if you require additional status, report, or state test cases.
include_object
is ON
{
"id": "1002d6bca6acdfcbb8442178",
"object": "event",
"type": "object.event",
"created_at": "2018-08-17T01:12:43Z",
"webhook_url": "https://notify.company.com/checkr",
"data": {
"object": {
"id": "a13f4827d8711ddc75abc56ct",
"object": "object",
"uri": "/v1/objects/a13f4827d8711ddc75abc56ct",
"created_at": "2018-08-17T01:10:21Z",
"completed_at": "2018-08-17T01:12:26Z",
// [...] full object included
}
}
}
Use webhooks to receive updates on objects created with the API and to kick off additional workflows based on these events. Each time an event that you subscribed to occurs, Checkr submits a POST request to the designated webhook URL with information about the event. When the include_object
option is ON, it also includes the related object.
The User-Agent for the requests will have the prefix Checkr-Webhook/
.
To receive webhooks, use the Checkr Dashboard to configure a Webhook URL in the Developer Settings. A maximum of two webhook URLs may be configured per environment (test and live). For more information about setting up webhooks, see the Account Settings article in the Checkr Help Center.
include_object
is OFF
{
"id": "1002d6bca6acdfcbb8442178",
"object": "event",
"type": "object.event",
"created_at": "2018-08-17T01:12:43Z",
"webhook_url": "https://notify.company.com/checkr",
"data": {
"object": {
"id": "a13f4827d8711ddc75abc56ct",
"object": "object",
"uri": "/v1/objects/a13f4827d8711ddc75abc56ct"
}
}
}
Parameter | Type | Description |
---|---|---|
id |
string | ID of the event. |
object |
string | Defines the object type: event . |
type |
string | The type of event. Values include: candidate.created , report.completed . |
created_at |
timestamp iso 8601 format | Timestamp for the event. |
webhook_url |
string | Webhook URL. |
data |
hash | Object associated with the event. |
include_object |
boolean | Should the related object be attached to webhook payload. |
Type | Format | Description |
---|---|---|
HTTP / HTTPS |
http(s)://(<user>:<password>@)<hostname>/<path> E.g.: https://notify.company.com/checkr |
Notes: The endpoint to be reached must be public. HTTP can be used only in a Test environment. Live environment webhooks must be HTTPS. Basic Auth is supported by adding username:password@ in front of the hostname, credentials must be URL escaped. |
SNS |
sns://<key_id>:<access_key>@<region>/<topic_owner>/<topic_name> E.g.: sns://AKI95AMUAD5K:a2n66fVKX7%2BYJKid3@us-east-1/12048/checkr |
AWS Simple Notification System (SNS) Notes: Access Key must have only the Publish to SNS right in IAM. Credentials must be URL escaped. |
Your endpoint should respond to webhooks as quickly as possible. To acknowledge receipt of a webhook, your endpoint must return a 2xx
HTTP status code. This status code should only indicate receipt of the message, not acknowledgment that it was successfully processed by your system. Any other information returned in the response headers or response body is ignored.
If a webhook is not successfully received for any reason, Checkr will continue trying to send it every minute for 10 minutes, then every hour for 24 hours.
Webhook logs can be found on the dashboard: https://dashboard.checkr.com/webhook_logs
Checkr does not guarantee the delivery of events in the order in which they are generated. For example, a report with a result
of consider
might generate the follow events:
report.completed
report.engaged
Your integration should not expect the delivery of these events to be in this order and should handle this accordingly. For example, you can fetch the report object, and look at report.assessment
if you happen to receive the report.completed
event later.
For greater security, verify that the requests you receive come from Checkr.
We pass along a hash signature with each request in the header X-Checkr-Signature. The hash signature is generated with the HMAC algorithm, using your API key as a key and SHA256 digest mode. When you receive a request, you can compute a hash and ensure that the one from Checkr matches.
Note: Accounts without an API key will have X-Checkr-Signature set to "Please create an API key to check the authenticity of our webhooks."
Example hash signature computation:
printf "$compact_json" | openssl sha256 -hmac "$PARTNER_APP_CLIENT_SECRET"
In this example, $compact_json
is the “non-pretty print” version of a JSON object. For example, you can get the compact version of a json file with the jq
tool with: compact_json=$(jq -c < example_response.json)
.
Code examples on how to do this can be found here.
While webhooks are helpful for updates, they are not foolproof. In some cases, report updates can be sent in rapid succession based on multiple events within the Checkr environment, and may be "mis-heard". For robust webhook handling, we recommend that you account for the following:
As a best practice, Checkr recommends that you build a safety net to account for duplicate reports. One option might be to build in a function ahead of the status tracker, which copies only one report.completed
update per Candidate or Report. This works well with an additional time threshold assigned. (For example, a report is only considered a duplicate if it's within 60 minutes of a previous iteration of that report.)
To address missed webhook updates, you may also consider adding a function to send an alert if no report.completed
update is sent within a certain number of days.
{
"id": "58f8e550d991bb000db04005",
"object": "event",
"type": "candidate.created",
"created_at": "2017-04-20T16:44:00Z",
"webhook_url": "https://yourcompany.com/checkr/incoming",
"data": {
"object": {
"id": "c373384e71a9a02098cb7421",
"object": "candidate",
"uri": "/v1/candidates/e44aa283528e6fde7d542194",
"created_at": "2017-04-18T18:37:34Z",
"first_name": "John",
"last_name": "Smith",
"middle_name": "Alfred",
"mother_maiden_name": null,
"dob": "1990-10-31",
"ssn": "XXX-XX-1111",
"email": "john.smith@example.org",
"zipcode": "48071",
"phone": "5555555555",
"driver_license_state": "CA",
"driver_license_number": "F111111",
"copy_requested": true,
"previous_driver_license_state": null,
"previous_driver_license_number": null,
"adjudication": "engaged",
"custom_id": null,
"no_middle_name": false,
"report_ids": [
"4722c07dd9a10c3985ae432a"
],
"geo_ids": [],
"metadata": {
"custom_key": "custom_value"
}
}
},
"account_id": "e9b18321a51bdab376045be8"
}
Event | Description |
---|---|
candidate.created |
A new Candidate has been created. |
candidate.id_required |
An exception has been raised requiring a copy of the Candidate's identification. |
candidate.driver_license_required |
An exception has been raised requiring a copy of the Candidate's driver license. |
candidate.updated |
A Candidate has been updated. |
candidate.pre_adverse_action |
An Adverse Action has been initiated on the Candidate. |
candidate.post_adverse_action |
An Adverse Action has been completed on the Candidate. |
{
"id": "1002d6bca6acdfcbb8442178",
"object": "event",
"type": "invitation.expired",
"created_at": "2017-04-20T16:44:00Z",
"webhook_url": "https://yourcompany.com/checkr/incoming",
"data": {
"object": {
"id": "16241770f7f7be1c57c85176",
"status": "expired",
"uri": "/v1/invitations/16241770f7f7be1c57c85176",
"invitation_url": "https://apply.checkr.com/invite/yourcompany/7499b8c558a6",
"completed_at": null,
"deleted_at": null,
"expires_at": "2017-05-21T17:45:34Z",
"package": "tasker_pro",
"object": "invitation",
"created_at": "2017-05-14T17:45:34Z",
"candidate_id": "fcb0084f6cb2423c069a35b3",
"report_id": null
}
},
"account_id": "e9b18321a51bdab376045be8"
}
Event | Description |
---|---|
invitation.created |
An Invitation has been created. |
invitation.completed |
An Invitation has been completed. |
invitation.expired |
An Invitation has expired. |
invitation.deleted |
An Invitation has been canceled. |
{
"id": "id",
"object": "event",
"type": "verification.processed",
"created_at": "2018-07-12T00:06:40Z",
"data": {
"object": {
"id": "verification_id",
"object": "verification",
"uri": "/v1/reports/report_id/verifications/verification_id",
"created_at": "2018-07-12T00:06:39Z",
"completed_at": "2018-07-12T00:17:02Z",
"processed_at": "2018-07-12T00:17:04Z",
"verification_type": "ssn_confirmation",
"verification_url": "https://verifications.checkr.com/verifications/verification_id",
"report_id": "report_id"
}
},
"account_id": "account_id"
}
Verification events are issued during the Exception process when a candidate is issued or has responded to a request to verify submitted PII.
Verification events are issued for exceptions which occur to ask candidates to confirm their Social Security Number, Driver License information, or Education and Employment Verification information.
The list of possible verification types that are in the webhook payload (verification_type inside the data object) can be found here.
Note: When verifications are automatically processed, and do not require manual input, the verification.processed
webhook is sent immediately after the verification.completed
webhook. These two webhooks may not arrive “in order”.
Event | Description |
---|---|
verification.created |
A verification is created and a request to upload a document or enter the data is forwarded to the candidate. |
verification.completed |
A document is uploaded or data is entered by the candidate. |
verification.processed |
The data gathered by the verification is processed manually or automatically and a decision is made for the continuation of the background check. |
{
"id": "507f1f77bcf86cd799439011",
"object": "event",
"type": "report.completed",
"created_at": "2014-01-18T12:34:00Z",
"webhook_url": "https://yourcompany.com/checkr/incoming",
"data": {
"object": {
"id": "4722c07dd9a10c3985ae432a",
"object": "report",
"uri": "/v1/reports/532e71cfe88a1d4e8d00000d",
"created_at": "2014-01-18T12:34:00Z",
"received_at": "2014-01-18T12:34:00Z",
"status": "complete",
"result": "clear",
"package": "driver_pro",
"candidate_id": "e44aa283528e6fde7d542194",
"ssn_trace_id": "539fd88c101897f7cd000001",
"sex_offender_search_id": "539fd88c101897f7cd000008",
"national_criminal_search_id": "539fd88c101897f7cd000006",
"county_criminal_search_ids": [
"539fdcf335644a0ef4000001",
"532e71cfe88a1d4e8d00000c"
],
"state_criminal_search_ids": [
"539fdcf335644a0ef4000003",
"532e71cfe88a1d4e8d000004"
],
"motor_vehicle_report_id": "539fd88c101897f7cd000007"
}
},
"account_id": "e9b18321a51bdab376045be8"
}
Event | Description |
---|---|
report.created |
A new Report has been created. |
report.updated |
A Report has been updated while the background check is run. This event is triggered on select update events, which include:
|
report.canceled |
A Report has been canceled. |
report.upgraded |
A Report has been upgraded. Upgrades can be triggered either from an API call or from the Dashboard ("Upgrade" button). This is useful if you want to run a package (such as an MVR) and then upgrade it on completion (for example: add a County Criminal Search). |
report.completed |
A Report has been completed. |
report.suspended |
A Report has been suspended. Checkr is waiting for the candidate to provide additional documentation. |
report.resumed |
A Report has resumed. (The candidate has provided documentation to a previously "suspended" Report.) |
report.disputed |
A Report has been disputed by a candidate. Once a dispute has been completed, Checkr will trigger the report.completed webhook again with the appropriate Report status. |
report.pre_adverse_action |
The Pre-Adverse Action notice has been sent to the candidate of that report. |
report.post_adverse_action |
The Post-Adverse Action notice has been sent to the candidate of that report. |
report.engaged |
A Report has been adjudicated as "engaged". Use this event to track either all candidates you have officially engaged, or simply those candidates with a "consider" background check report that you have engaged. This can be triggered either from an API call or from the dashboard ("Engage" button). |
{
"id": "5c4fee84d5abd60049eaa4fe",
"object": "event",
"type": "adverse_action.notice_not_delivered",
"created_at": "2019-01-29T06:11:16Z",
"data": {
"object": {
"id": "5c4f46eb805e59e228baacdd",
"object": "adverse_action",
"uri": "/v1/adverse_actions/5c4f46eb805e59e228baacdd",
"status": "pending",
"created_at": "2019-01-28T18:16:11Z",
"canceled_at": null,
"post_notice_scheduled_at": null,
"post_notice_ready_at": "2019-02-04T18:16:11Z",
"delivery": {
"state": "error",
"updated_at": "2019-01-29T06:11:15Z",
"reason": "No MX for bad-email-domain-client.com"
},
"individualized_assessment_engaged": false,
"report_id": "report_id",
"adverse_items": [
{
"id": "62532b9f6dd2279acc5eb3574bad5bc085892ecc",
"object": "adverse_item",
"text": "** ACCIDENT **"
},
{
"id": "418759b62961971c0ce8d7a6858b6c6f457400d5",
"object": "adverse_item",
"text": "** ACCIDENT **"
},
{
"id": "e911042a437d735bbcbb6a98ab500bc62fc2b88e",
"object": "adverse_item",
"text": "FAILURE TO WEAR SEAT BELT"
},
{
"id": "09d83492f6a15b41e3e5c48a970df3a4f53e660c",
"object": "adverse_item",
"text": "OBSTRUCTING PASSAGE OF OTHER VEHIC"
}
]
}
},
"account_id": "account_id"
}
Event | Description |
---|---|
adverse_action.notice_not_delivered |
The Adverse Action notice is confirmed to be undeliverable to the candidate of that report. User action is required. |
{
"id": "1002d6bca6acdfcbb8442178",
"object": "event",
"type": "package.created",
"created_at": "2017-04-20T16:44:00Z",
"webhook_url": "https://yourcompany.com/checkr/incoming",
"data": {
"object": {
"id": "e44aa283528e6fde7d542194",
"object": "package",
"uri": "/v1/packages/e44aa283528e6fde7d542194",
"apply_url": "https://apply.checkr.com/apply/customer-services-inc/532c20ea819b",
"created_at": "2014-01-18T12:34:00Z",
"deleted_at": null,
"name": "Driver Pro",
"slug": "driver_pro",
"price": 6500,
"screenings": [
{
"type": "ssn_trace",
"subtype": null
},
{
"type": "county_criminal_search",
"subtype": "7years"
},
{
"type": "national_criminal_search",
"subtype": "standard"
},
{
"type": "sex_offender_search",
"subtype": null
},
{
"type": "global_watchlist_search",
"subtype": null
},
{
"type": "motor_vehicle_report",
"subtype": null
}
]
}
}
}
Event | Description |
---|---|
package.created |
A Package has been created. |
package.updated |
A Package has been updated. |
package.deleted |
A Package has been deleted. |
{
"id": "6164822db059440001101d93",
"object": "event",
"type": "continuous_check.confirmation_required",
"created_at": "2021-10-11T18:27:57Z",
"data": {
"object": {
"object": "continuous_check",
"id": "d56cdf24dca36bd1cb65aebe",
"candidate_id": "7c445ec8dd78d534436c6ead",
"created_at": "2021-09-02T17:22:17Z",
"node": "zpy8orej4r614ize",
"type": "mvr",
"work_locations": [
{
"country": "US",
"state": "CA",
"city": "San Francisco"
}
]
}
},
"account_id": "57f79ea983381984e6a6e61a"
}
Event | Description |
---|---|
continuous_check.subscription_error |
An error occurred when attempting to enroll a Candidate in Continuous MVR. |
continuous_check.confirmation_required |
A Candidate has been unenrolled from Continuous MVR due to stale or invalid PII. The Candidate sumbitted updated information through the Checkr exception process. Action is required to re-enroll the Candidate. |
Checkr partners with leading Staffing, On-Demand, Applicant Tracking Systems, and HR Systems to bring background checks to your customers. As a Checkr Partner, you can leverage the Checkr API to seamlessly connect your customers' Checkr accounts and integrate the background check process into your applications. Checkr's self-serve sign-up flow is fast, easy, and allows your customers to start running background checks within minutes after their account is credentialed.
If you are interested in partnering with Checkr, submit our Checkr Partner Application form to connect with our Business Development team.
Please see our Checkr Partner Developer Guides for more complete information on building your partner integration with Checkr, and allowing your customers to use Checkr functionality from within your app.
The Checkr API offers significant flexibility and opportunity for developers to build a unique background screening program tailored to their product or business needs. This section describes additional features and capabilities that our customers find valuable.
Checkr allows customers to create fully custom application flows for their candidates, using the Reports resource to build a self-hosted flow.
In this flow, you must collect and store both the candidate’s information and their consent within your application. You must also provide candidates the appropriate state- and city-specific disclosures for each screening type. Once obtained, you must store your candidates’ consent to the background check, both to maintain proof that consent was granted, and to provide proof of consent for Checkr’s ongoing evaluation of customer compliance (annual compliance audits).
Once all required information is present on the Candidate resource, creating a Report will initiate the background check.
For more information on your obligations under FCRA, and Checkr’s responsibilities as a Consumer Reporting Agency (CRA), check out our Compliance resources in the Help Center, particularly our articles about obligations under FCRA and disclosures and authorizations.
Note: Some screening types are not supported with the Reports flow, such as credit checks and complex occupational health screenings. Other screening types, like employment and education verifications, are supported but not recommended with this flow, as they require significant data entry. For more information, see Reports below.
$ curl -X POST https://api.checkr.com/v1/reports \
-u [YOUR_API_KEY]: \
-d package=dunder_mifflin_executive \
-d candidate_id=551564b7865af96a28b13f36
Create a Report for an existing Candidate object. Use your API key and Candidate ID in the cURL command shown to the right.
Notes:
{
"id": "a13f4827d8711ddc75abc56ct",
"object": "test_report",
"uri": "/v1/reports/a13f4827d8711ddc75abc56ct",
"status": "pending",
"result": null,
"created_at": "2018-08-17T01:10:21Z",
"completed_at": null,
"revised_at": null,
"upgraded_at": null,
"turnaround_time": null,
"package": "dunder_mifflin_executive",
"tags": [],
"adjudication": null,
"assessment": null,
"candidate_id": "551564b7865af96a28b13f36",
"county_criminal_search_ids": null,
"document_ids": [
"865de4344ac6d05209c83ef5"
],
"federal_criminal_search_id": "5b64c62b67abb4002d3ec763",
"global_watchlist_search_id": "5b64c5cf67abb400353ec6f7",
"national_criminal_search_id": "5b64c5cf67abb400353ec6f5",
"personal_reference_verification_ids": [],
"professional_reference_verification_ids": [],
"sex_offender_search_id": "5b64c5cf67abb400353ec6f6",
"ssn_trace_id": "5b64c5cf67abb400353ec6f3",
"state_criminal_search_ids": [],
"terrorist_watchlist_search_id": "5b64c5cf67abb400353ec6f7",
"facis_search_id": null,
"arrest_search_id": null,
"motor_vehicle_report_id": null
}
Checkr responds immediately with the full Report object, which includes the ID of the Report and a URI that points to the new Report object.
Store the resulting Report ID and any of the requested Screening IDs. The ID for this new Report object is required to retrieve the Report. (Checkr will return IDs for all Screenings included in the requested Package. All other Screening IDs will be returned null
.)
In addition to offering "point-in-time" background checks, Checkr offers ongoing check services through our Subscription and Continuous Check products.
A Subscription enables customers to order a repeating background check on a candidate on a user-defined time interval. Candidates must first complete an initial background check, after which customers may create a Subscription to repeat that background check on a user-defined interval. Subscriptions can be created, modified, or deleted both through the Checkr Dashboard and the Checkr API.
For more information, see Subscriptions: Run recurring background checks in the Checkr Help Center, or the Subscription resource below.
Continuous Checks allow customers to monitor their candidates' records. Continuous Check monitors real-time data sources, and looks for changes in a candidate's record. If Checkr identifies a change in the candidate's history, Continuous Check will automatically kick off follow-up searches in the appropriate jurisdictions and generate a new background check report.
For more information, see Continuous Check: The new standard of safety in the Checkr Help Center, or the Continuous Checks resource below. For information on using the Checkr Dashboard to order a Continuous Check package on a candidate, see Continuous checks in the Checkr Help Center.
While both Continuous Check and Subscriptions allow you to monitor your candidates' record, they should not be understood as equivalent to one another. Subscriptions generate a new report according to your defined cadence. Continuous Check continuously monitors multiple data sources, and generates a new report only if a change in your candidate's record is found. If you have additional questions about what makes the most sense for your business, please reach out to your Checkr Account Executive or Customer Success Manager.
Checkr also offers the ability to "upgrade" a report based on a prior set of screening results. The most common use case for this feature is to order a Package that includes both a Motor Vehicle Record (MVR) and a County Criminal Search. The report can be "upgraded" to run the County Criminal Search only after the MVR returns with a result. Checkr facilitates the following workflow:
POST
request to Checkr's /reports/{id}
endpoint with the same Report ID and the new Package to requestFor more information on upgrading a Report, please see Update an existing Report below.
Please note: Only reports which include a Candidate SSN may be upgraded, and only within 30 days of Report creation. Attempts to upgrade a report which does not include an SSN will return a 400 error: "Candidate must have SSN to upgrade report." Requests to upgrade an older report will result in a 400 error, "Report too old to upgrade."
To use the Candidate SSN endpoint, you must generate an RSA key-pair for your account, and share the public key with Checkr. Checkr will use this public key to encrypt the SSN and securely share it with your integration.
Run the following command in a bash session to generate a private key. This will generate a file named private.pem containing your private key.
openssl genrsa -out private.pem -aes256 4096
Once your private key is generated, run the following command. This will generate a file named public.pem containing your public key.
openssl rsa -in private.pem -out public.pem -outform PEM -pubout
With both keys generated, send your public key to your Customer Success Manager. Do not share your private key. If your private key is exposed let us know as soon as possible so that we can secure your candidates' information.
Checkr’s Test Mode is a legacy testing environment that provides very limited testing scenarios and should be used only to test basic connectivity. Use the Staging Account described above for more in-depth testing.
Note: Test Mode does not support Account Hierarchy or Work Location. If your account has this functionality enabled (check if “Account Hierarchy” tab exists under “Account Settings”), you cannot use Test Mode.
The following test data is available for Test Mode:
Test SSNs
clear
.consider
.pending
.Test driver licenses
clear
.consider
.The test environment's API calls, responses, and webhooks follow the same pattern and response structure as those of the production environment.
$ curl -X POST https://api.checkr.com/v1/candidates \
-H "Content-Type: application/json" \
-u 83ebeabdec09f6670863766f792ead24d61fe3f9: \
-d '{"first_name": "John", "middle_name": "Alfred", "last_name": "Smith", "email": "john.smith@gmail.com"}'
The Content-Type
entity header is used to describe the media type of a resource. In requests, a Content-Type
header tells the server what type of data is being sent. In responses, it tells the client what type of data the returned content actually is.
Our default is to accept data as application/x-www-form-urlencoded (which is typical for most websites you interact with), but you are free to send other data types, like application/json, as it suits you. Simply specify the Content-Type
in the header of the request.
$ curl -X GET https://api.checkr.com/v1/reports/59b650f567e1dd0f01422b92\
?include=candidate,ssn_trace,county_criminal_searches \
-u 83ebeabdec09f6670863766f792ead24d61fe3f9:
By default, an API response contains the requested resource, and provides the IDs of related resources. You can also request related resources to be embedded in the initial response.
The include
parameter specifies the names of resources that should be embedded in the response. Resources to embed must be comma-separated.
$ curl -X GET https://api.checkr.com/v1/candidates?page=2&per_page=25 \
-u 83ebeabdec09f6670863766f792ead24d61fe3f9:
{
"data": [
{
"id": "e44aa283528e6fde7d542194",
"object": "candidate",
"uri": "/v1/candidates/e44aa283528e6fde7d542194",
"created_at": "2014-01-18T12:34:00Z",
"first_name": "John",
"middle_name": "Alfred",
"no_middle_name": false,
"last_name": "Smith",
"mother_maiden_name": null,
"email": "john.smith@gmail.com",
"phone": "5555555555",
"zipcode": "90401",
"dob": "1970-01-22",
"ssn": "XXX-XX-4645",
"driver_license_number": null,
"driver_license_state": null,
"previous_driver_license_number": null,
"previous_driver_license_state": null,
"copy_requested": false,
"custom_id": null,
"report_ids": []
},
{
"id": "8b6eb2bf554ebbef7b6f885a",
"object": "candidate",
"uri": "/v1/candidates/8b6eb2bf554ebbef7b6f885a",
"created_at": "2014-01-18T12:34:00Z",
"first_name": "Michael",
"middle_name": null,
"no_middle_name": true,
"last_name": "Johnson",
"mother_maiden_name": null,
"email": "michael.johnson@gmail.com",
"phone": "5555555555",
"zipcode": "94407",
"dob": "1970-01-22",
"ssn": "XXX-XX-8605",
"driver_license_number": null,
"driver_license_state": null,
"previous_driver_license_number": null,
"previous_driver_license_state": null,
"copy_requested": false,
"custom_id": null,
"report_ids": []
}
],
"object": "list",
"next_href": null,
"previous_href": "http://api.checkr.com/v1/candidates?page=1&per_page=25",
"count": 27
}
Pagination is enabled for endpoints that return a list of records.
There are two parameters that control pagination: page
, which specifies the page number to retrieve, and per_page
, which indicates how many records each page should contain. The default value of per_page
is 25 records.
Parameters | Description |
---|---|
page |
integer greater than or equal to 1 |
per_page |
integer between 0 and 100 |
Paginated responses include the following attributes:
Attributes | Description |
---|---|
count |
integer the total number of items |
data |
array list of objects |
next_href |
string URI to fetch the next page of results |
object |
string "list" |
previous_href |
string URI to fetch the previous page of results |
$ curl -I -X GET https://api.checkr.com/v1/reports/59b650f567e1dd0f01422b92 \
-u 83ebeabdec09f6670863766f792ead24d61fe3f9:
< X-Ratelimit-Limit: 600
< X-Ratelimit-Remaining: 9
< X-Ratelimit-Reset: 2018-02-02T16:39:00Z
In order to provide a high-quality of service for all customers, our API is rate limited. The current limit is 600 requests per minute across all endpoints. We reserve the right to adjust the rate limit for given endpoints.
If the rate limit is exceeded, the API responds with a HTTP 429 "Too Many Requests"
status code. The response has a X-Ratelimit-Reset
header that tells you when the rate limit count will reset.
Here are the headers related to rate limiting that our API returns for any requests:
Header | Description |
---|---|
X-Ratelimit-Limit |
Number of requests allowed per minute |
X-Ratelimit-Remaining |
Remaining number of requests allowed for the current minute |
X-Ratelimit-Reset |
Time at which the rate limit count resets |
Here are some recommendations to stay under the limit:
$ curl -v -X POST https://api.checkr.com/v1/reports \
-u 83ebeabdec09f6670863766f792ead24d61fe3f9: \
-H 'Idempotency-Key: 40b23921-c005-4ec7-832a-3ae023dbbc11' \
-d package=driver_pro \
-d candidate_id=be529e5d8cc5ad26e655ce89
The Checkr API supports idempotency in POST requests. Use this feature to safely repeat POST requests without accidentally creating the same reports or candidates multiple times.
First, provide an Idempotency-Key: <key>
header to the POST request. This header value will be used server side to recognize retries of the same request.
The client side must then generate a unique value for every POST request, and re-use the same header value in any subsequent retry attempts. We recommend the use of V4 UUIDs to avoid collisions.
When serving the request with a new idempotency key, Checkr service will save the response (including status code, headers, body) for the first request if it is successful (2xx status), and return the saved response for later requests with the same idempotency key.
Note: The idempotency key expires after 24 hours. Retries with an expired idempotency key will be handled as new requests.
The Checkr API supports alphanumeric character input, as well as accented characters and some punctuation marks.
Corresponding regex character ranges: [a-zA-Z0-9ªµºÀ-ÖØ-öø-ÿ\-'., ]
ª | µ | º | À | Á | Â | Ã | Ä | Å | Æ |
---|---|---|---|---|---|---|---|---|---|
Ç | È | É | Ê | Ë | Ì | Í | Î | Ï | Ð |
Ñ | Ò | Ó | Ô | { | Ö | Ø | Ù | Ú | Û |
Ü | Ý | Þ | ß | à | á | â | ã | ä | å |
æ | ç | è | é | ê | ë | ì | í | î | ï |
ð | ñ | ò | ó | ô | õ | ö | ø | ù | ú |
û | ü | ý | þ | ÿ | ' | . | , | - |
Checkr has compiled the following table of valid driver license number input per state. To avoid errors, we suggest that you implement driver license number validation for both the Candidates and Driver Licenses endpoints.
State | Validation Criteria | Regex |
AL | 7-8 Numeric | /\A\d{7,8}\z/ |
AK | 7 Numeric | /\A\d{7}\z/ |
AZ | (1 Alpha + 8 Numeric) OR 9 Numeric | /\A[A-Z]{1}\d{8}\z/ OR /\A\d{9}\z/ |
AR | 9 Numeric | /\A\d{9}\z/ |
CA | 1 Alpha + 7 Numeric | /\A[A-Z]{1}\d{7}\z/ |
CO | 9 Numeric | /\A\d{9}\z/ |
CT | 9 Numeric | /\A\d{9}\z/ |
DE | 2-7 Numeric | /\A\d{2,7}\z/ |
DC | 7-9 Numeric | /\A\d{7,9}\z/ |
FL | 1 Alpha + 12 Numeric | /\A[A-Z]{1}\d{12}\z/ |
GA | 9 Numeric | /\A\d{9}\z/ |
HI | ("H" + 8 Numeric) or 9 Numeric | /\AH\d{8}\z/ OR /\A\d{9}\z/ |
ID | (2 Alpha + 6 Numeric + 1 Alpha) or 9 Numeric | /\A[A-Z]{2}\d{6}[A-Z]{1}\z/ OR /\A\d{9}\z/ |
IL | 1 Alpha + 11-12 Numeric | /\A[A-Z]{1}\d{11,12}\z/ |
IN | 10 Numeric | /\A\d{10}\z/ |
IA | 9 Numeric or (3 Numeric + 2 Alpha + 4 Numeric) | /(\A\d{9}\z)/ OR /(\A\d{3}[A-Z]{2}\d{4}\z)/ |
KS | "K" + 8 Numeric | /\A[K]{1}\d{8}\z/ |
KY | 1 Alpha + 8 Numeric | /\A[A-Z]{1}\d{8}\z/ |
LA | ("0" + 7 Numeric) OR ("0" + 8 Numeric) OR 7 Numeric or 8 Numeric | /\A[0]{0,1}\d{7,8}\z/ |
ME | 7 Numeric | /\A\d{7}\z/ |
MD | (1 Alpha + 12 Numeric) OR ("MD" + 11 Numeric) | /\A[A-Z]{1}\d{12}\z/ OR /\AMD\d{11}\z/ |
MA | ("SA" + 7 Numeric) OR ("S" + 8 Numeric) OR 9 Numeric | \ASA\d{7}\z OR \AS\d{8}\z OR \A\d{9}\z |
MI | 1 Alpha + 12 Numeric | /\A[A-Z]{1}\d{12}\z/ |
MN | 1 Alpha + 12 Numeric | /\A[A-Z]{1}\d{12}\z/ |
MS | 9 Numeric | /\A\d{9}\z/ |
MO | 9 Numeric OR (1 Alpha + 5-9 Numeric) OR (3 Numeric + 1 Alpha + 6 Numeric) | /(\A\d{9}\z)/ OR /(\A[A-Z]{1}\d{5,9}\z)/ OR /(\A\d{3}[A-Z]{1}\d{6}\z)/ |
MT | 13 Numeric or 9 Alpha-Numeric or (3 Alpha + 10 Numeric) | /(\A\d{13}\z)/ OR
/(\A(\d|[A-Z]){9}\z)/ OR \ /(\A[A-Z]{3}\d{10}\z)/ |
NE | 1 Alpha + 3-8 Numeric | /\A[A-Z]{1}\d{3,8}\z/ |
NV | 10 Numeric | /\A\d{10}\z/ |
NH | (2 Numeric + 3 Alpha + 5 Numeric) OR ("NHL" + 8 Numeric) | /(\A\d{2}[A-Z]{3}\d{5}\z)/ OR /(\ANHL\d{8}\z)/ |
NJ | 1 Alpha + 14 Numeric | /\A[A-Z]{1}\d{14}\z/ |
NM | 9 Numeric | /\A\d{9}\z/ |
NY | 9 Numeric OR 1 Alpha + 18 Numeric | /(\A\d{9}\z)/ OR /(\A[A-Z]{1}\d{18}\z)/ |
NC | 1-12 Numeric | /\A\d{1,12}\z/ |
ND | 9 Alpha-Numeric | /\A(\d|[A-Z]){9}\z/ |
OH | 2 Alpha + 6 Numeric OR 8 Numeric | /\A[A-Z]{2}\d{6}\z/ OR /(\A\d{8}\z)/ |
OK | (1 Alpha + 9 Numeric) or 9 Numeric | /(\A[A-Z]{1}\d{9}\z)/ OR /(\A\d{9}\z)/ |
OR | 5-7 Numeric OR (1 Alpha + 6 Numeric) | /(\A\d{5,7}\z)/ OR /(\A[A-Z]{1}\d{6}\z)/ |
PA | 8 Numeric | /\A\d{8}\z/ |
PR | 5-7 Numeric OR 9 Numeric | /\A\d{5,7}\z/ OR /\A\d{9}\z/ |
RI | 7-8 Numeric OR ("V" + 6 Numeric) | /(\A\d{7,8}\z)/ OR /(\AV\d{6}\z)/ |
SC | 3-10 Numeric | /\A\d{3,10}\z/ |
SD | 6-9 Numeric | /\A\d{6,9}\z/ |
TN | 7-9 Numeric | /\A\d{7,9}\z/ |
TX | 7-8 Numeric | /\A\d{7,8}\z/ |
UT | 4-10 Numeric | /\A\d{4,10}\z/ |
VT | 8 Numeric or (7 Numeric + "A") | /(\A\d{8}\z)/ OR /(\A\d{7}A\z)/ |
VA | (1 Alpha + 8 Numeric) OR 9 Numeric | /\A[A-Z]{1}\d{8}\z/ OR /\A\d{9}\z/ |
WA | (4-8 Alpha + 2-3 Numeric + 2 Alpha-Numeric) OR ("WDL" + 9 Alpha-Numeric) | /\A[A-Z*]{4,8}\d{2,3}(\d|[A-Z]){2}\z/ OR /\AWDL([A-Z]|\d){9}\z/ |
WV | 7 Alpha-Numeric | /\A([A-Z]|\d){7}\z/ |
WI | 1 Alpha + 13 Numeric | /\A[A-Z]{1}\d{13}\z/ |
WY | 9 Numeric | /\A\d{9}\z/ |
The Checkr API validates submitted email addresses using the industry standard RFC 5322. The string length must be <=255, and the domain must be valid and configured to accept email. (For example: gmail.com is a valid domain, while gmeil.con is not.)
To avoid errors, we suggest that you validate emails used in your candidate creation requests.
Checkr's product incorporates SSN field controls designed to not accept SSNs with the following characteristics:
Checkr's API offers a number of error codes to facilitate your building and troubleshooting. Some common error codes include:
Status Code | Response |
---|---|
400 | SSN is invalid |
400 | Zipcode is invalid |
400 | Email is not a valid email address |
400 | First name must only contain letters, numbers, spaces, hyphens, apostrophes, periods, and commas |
400 | Last name must only contain letters, numbers, spaces, hyphens, apostrophes, periods, and commas |
400 | Report is too old to upgrade |
400 | New package does not add any screenings |
400 | Candidate must have a driver license number and a driver license state for the package mvr |
400 | Report has a pre-existing adverse action. See https://docs.checkr.com/#operation/updateReport |
400 | SSN is invalid. TIN was provided. |
400 | SSN has already been taken |
400 | First name must only contain letters, numbers, spaces, hyphens, apostrophes, periods, and commas", "Last name must only contain letters, numbers, spaces, hyphens, apostrophes, periods, and commas |
400 | Candidate must_not have middle name when no_middle_name flag is set to true for the candidate report_id= |
400 | Report driver license state not supported or not enabled for account |
400 | Candidate must be at least 16 years old |
400 | Candidate must be at least 18 years old |
400 | Candidate must have SSN for the package driver_premium |
400 | Candidate has reached the limit of Reports allowed |
400 | Middle name must only contain letters, numbers, spaces, hyphens, apostrophes, periods, and commas. |
400 | Number Driver license number must only contain letters, numbers, spaces, hyphens, and asterisks |
400 | Candidate must have middle name when no_middle_name flag is set for the candidate report_id= |
400 | Number can't be blank, State can't be blank, State is not a valid US state |
400 | No middle name can not be updated, No middle name must have middle name when no_middle_name flag is set to false for the candidate candidate_id= |
403 | Forbidden |
403 | Sorry, your account is not approved for production |
403 | Candidate has requested that their PII be removed |
409 | Duplicate geo, name: peninsulasw_wa, state: WA already exists |
409 | Duplicate report detected. No more than 3 reports per candidate can be created within a 24 hour period |
409 | Duplicate candidate detected. No more than 2 duplicate candidates can be created within a 24 hour period |
Screenings can be canceled due to various scenarios. Here is a list of the current cancellation reasons and their descriptions.
Reason | Description |
---|---|
candidate_pii_updated_customer_requested | Customer updated candidate PII prior to screening completion |
exception_ssn_trace | SSN Trace completed with an exception prior to screening completion |
source_inaccessible_closed_court | Court closed or has limited access to court records |
complete_now_customer_requested | Customer requested Complete Now prior to screening completion |
missing_required_information | Required information not received |
vendor_unable_to_complete | Vendor unable to complete screening |
vendor_account_deauthorized | Vendor deauthorized account |
international_entry_not_supported | Screening does not support international entries |
no_history_required_information | Candidate declared no history |
profile_on_hold_customer_requested | Customer requested candidate profile on hold |
candidate_withdrew_consent | Candidate withdrew consent |
minors_package_not_enabled | Package not configured to allow candidates under age 18 |
candidate_below_minimum_age | Candidate is below the minimum age for a background check |
exception_mvr | MVR canceled with an exception |
customer_account_deauthorized | Customer account was deauthorized |
Verification type values that indicate additional information or actions requested from a candidate. These types are shown inside of webhooks and from the API for verifications. For more information about verifications please visit the links for the webhook events or the api.
Type |
---|
candidate_employment_history |
driver_license |
driver_license_history |
education |
id |
id_document |
license_document |
passport_document |
previous_license_document |
ssn_confirmation |
ssn_document |
matrix |
consent |
The Account resource includes account information and settings. Account information can be
updated from the Dashboard. Some Account settings, like available_screenings
, can be updated
only by Checkr. Contact our Customer Success team for more information.
Returns Account details for the authenticated account.
$ curl -X GET https://api.checkr.com/v1/account \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
{- "id": "string",
- "object": "account",
- "adverse_action_email": "john.doe@example.com",
- "api_authorized": true,
- "authorized": true,
- "available_screenings": [
- "county_civil_search",
- "county_criminal_search",
- "municipal_criminal_search",
- "education_verification",
- "employment_verification",
- "federal_civil_search",
- "federal_criminal_search",
- "motor_vehicle_report",
- "national_criminal_search",
- "sex_offender_search",
- "ssn_trace",
- "state_criminal_search",
- "international_adverse_media_search",
- "international_education_verification"
], - "billing_email": "john.doe@example.com",
- "company": {
- "name": "Acme Corporation",
- "dba_name": "ACME",
- "street": "123 Main St",
- "city": "Wilmington",
- "state": "DE",
- "zipcode": "19801",
- "phone": "206-555-0100",
- "industry": "52-59",
- "incorporation_state": "DE",
- "incorporation_type": "llc"
}, - "compliance_contact_email": "compliance.team@example.com",
- "created_at": "2020-01-07T00:26:49Z",
- "default_compliance_city": "San Francisco",
- "default_compliance_state": "CA",
- "geos_required": false,
- "name": "Acme Corp",
- "purpose": "employment",
- "segmentation_enabled": true,
- "support_email": "support@example.com",
- "support_phone": "206-555-0188",
- "technical_contact_email": "jane.smith@example.com",
- "uri": "/v1/accounts/e44aa283528e6fde7d542194",
- "uri_name": "acme-corp"
}
Creates a customer Account associated with your Partner Application. Only Checkr Partners are authorized to use this endpoint.
client_id required | string Client credentials provided as part of your Partner Application. |
oauth_authorize | boolean Default: false Allows skipping of the /oauth/authorize call |
name required | string Name of Account displayed in the Dashboard. |
default_compliance_city | string Nullable Fallback compliance city if candidate location is not provided. |
default_compliance_state | string Nullable Fallback compliance state if candidate location is not provided. Format: |
purpose required | string Permissible purpose to run background checks. Determines which background checks the Account is credentialed for. |
required | object |
required | object |
$ curl -X POST https://api.checkr.com/v1/accounts \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9: \ -d client_id=56269e3411a549fd07ed8d92 \ -d name=Acme+Corporation \ -d default_compliance_state=CA \ -d purpose=employment \ -d user[full_name]=Jeanette+Hughes \ -d user[email]=user@example.com \ -d company[dba_name]=Acme \ -d company[industry]=72 \ -d company[street]=123+Main+Street \ -d company[city]=San Francisco \ -d company[state]=CA \ -d company[zipcode]=94107 \ -d company[tax_id]=123456789 \ -d company[incorporation_state]=CA \ -d company[incorporation_type]=association \ -d company[phone]=206-555-0100 \ -d company[website]=https%3A%2F%2Fwww.example.com
{- "id": "string",
- "object": "account",
- "adverse_action_email": "john.doe@example.com",
- "api_authorized": true,
- "authorized": true,
- "available_screenings": [
- "county_civil_search",
- "county_criminal_search",
- "municipal_criminal_search",
- "education_verification",
- "employment_verification",
- "federal_civil_search",
- "federal_criminal_search",
- "motor_vehicle_report",
- "national_criminal_search",
- "sex_offender_search",
- "ssn_trace",
- "state_criminal_search",
- "international_adverse_media_search",
- "international_education_verification"
], - "billing_email": "john.doe@example.com",
- "company": {
- "name": "Acme Corporation",
- "dba_name": "ACME",
- "street": "123 Main St",
- "city": "Wilmington",
- "state": "DE",
- "zipcode": "19801",
- "phone": "206-555-0100",
- "industry": "52-59",
- "incorporation_state": "DE",
- "incorporation_type": "llc"
}, - "compliance_contact_email": "compliance.team@example.com",
- "created_at": "2020-01-07T00:26:49Z",
- "default_compliance_city": "San Francisco",
- "default_compliance_state": "CA",
- "geos_required": false,
- "name": "Acme Corp",
- "purpose": "employment",
- "segmentation_enabled": true,
- "support_email": "support@example.com",
- "support_phone": "206-555-0188",
- "technical_contact_email": "jane.smith@example.com",
- "uri": "/v1/accounts/e44aa283528e6fde7d542194",
- "uri_name": "acme-corp"
}
Use the Hierarchy endpoint to structure your Account as a grouping of individual entities (Nodes) that represent your business with respect to your hiring and background check needs.
The parent-child relationship of Nodes may then be used to manage the relationship of your Packages and other account settings to Users and Candidates within your Account. Once defined, use the Checkr Dashboard to assign Nodes to Users, Packages, your Positive Adjudication Matrix, and other aspects of your Checkr Account.
Specifying a unique ID (custom_id) for each Node in the hierarchy allows you to edit the structure of your hierarchy without dissociating any Packages, PAMs, or Users assigned directly to the individual nodes. As nodes are moved to different locations within the hierarchy they will inherit Packages or PAMs from their new parent that may differ from the last, but Packages assigned directly to the node will not change.
Creates a new or replaces an existing Account Hierarchy.
The Hierarchy endpoint performs ingestion asynchronously. Check the status
of the ingestion by calling GET /v1/hierarchy/status
. Once ingested, use the Checkr Dashboard to assign your nodes to Packages, PAMs, and Users.
required | Array of objects (HierarchyNode) |
$ curl -X POST https://api.checkr.com/v1/hierarchy \ -H 'Content-Type: application/json' \ -u d3a265269d18997528b04cfa82bc6a108c1b8553: \ -d '{ "nodes": [{"name":"Acme Staffing", "tier": "department", "custom_id": "zpy8orej4r614ize"}, {"name":"Drivers Staffing", "tier": "divison", "custom_id": "ocquzig4k3whppfx", "parent_custom_id": "zpy8orej4r614ize"}]}'
{- "sync_id": "account-da78fa2cd1e6ebee4b5975aa",
- "time": "2020-02-11T00:27:14Z"
}
Note: This endpoint is deprecated and will no longer be supported. Please use the new List existing Nodes endpoint instead.
Retrieves the current Hierarchy for the Account.
Returns the account hierarchy in its entirety, or from a specific node to its children. The returned JSON object will include the Packages assigned to each node in the dashboard. This is useful for building UIs that truncate the list of Packages displayed to a requester, or display only the nodes that are relevant to the requester.
Output is arranged hierarchically, with child nodes accessible through the parent node. Customers without large hierarchy mode enabled who do not specify pagination parameters will be returned the entire hierarchy. Customers with large hierarchy mode enabled and pagination parameters specified in this request will be returned the given page and number of results per page. If pagination parameters are not included, only the first page of the hierarchy will be returned.
Note: Customers with large hierarchy mode enabled will see a different response. Please reach out to clients@checkr.com if you have any questions.
node_custom_ids | Array of strings An array of |
page | number Nullable Specifies the page to retrieve. The default page is 1. |
per_page | number Nullable Indicates how many nodes each page should contain. The default per_page value is 20. |
$ curl https://api.checkr.com/v1/hierarchy \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
{- "sync_id": "account-da78fa2cd1e6ebee4b5975aa",
- "time": "2020-01-01T08:00:00Z",
- "nodes": [
- {
- "name": "Acme Staffing",
- "custom_id": "zpy8orej4r614ize",
- "tier": "department",
- "children": [
- { }
]
}
]
}
Adds new nodes to an existing Account Hierarchy.
This endpoint creates the nodes synchronously.
required | Array of objects (HierarchyNode) |
$ curl -X POST https://api.checkr.com/v1/hierarchy/nodes \ -H 'Content-Type: application/json' \ -u d3a265269d18997528b04cfa82bc6a108c1b8553: \ -d '{ "nodes": [{"name":"Acme Staffing", "tier": "department", "custom_id": "zpy8orej4r614ize"}, {"name":"Drivers Staffing", "tier": "divison", "custom_id": "ocquzig4k3whppfx", "parent_custom_id": "zpy8orej4r614ize"}]}'
null
Returns the status of the latest Hierarchy ingestion request.
This call requires no input, and is provided as a means to determine the progress of an
asynchronous POST /hierarchy
request.
$ curl https://api.checkr.com/v1/hierarchy/status \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
{- "hierarchy_present": true,
- "hierarchy_pending": false,
- "latest_ingestion": {
- "sync_id": "account-da78fa2cd1e6ebee4b5975aa",
- "time": "2020-01-01T08:00:00Z",
- "successful": false,
- "errors": [
- "Row 1: Validation failed: Name required"
]
}
}
Nodes are the individual entities that comprise an Account Hierarchy. If hierarchy is enabled for your Checkr Account, this endpoint may be used to retrieve a list of all Account Nodes. To create Nodes, use the Create Hierarchy endpoint.
Returns a list of existing Nodes that make up the current Account Hierarchy.
If include=packages
is passed, each Node object in the response will include a "packages" field. This will be an array of strings representing the slugs of the account Packages that are assigned (directly or indirectly) to the given Node. This field can be used to build UIs that truncate the list of Packages displayed to a requester, or to display only the nodes that are relevant to the requester.
If include=packages
is not passed, no package information will be included in the response.
This endpoint uses pagination; please see the corresponding reference page for details.
include | string Includes a "packages" array with each Node object, containing a list of slugs for packages that are assigned to that node or its ancestors. Example: include=packages |
page | number Nullable Specifies the page number to retrieve. |
per_page | number Nullable Indicates how many records each page should contain. The default value is 25 records. |
order_by | string Nullable Returns records sorted by custom_id or created_at. If neither is specified, records will be sorted by created_at. Example: order_by=custom_id |
order | string Nullable Returns records listed in ascending or descending order of the order_by parameter. If neither is specified, records will be listed in ascending order. Example: order=desc |
$ curl https://api.checkr.com/v1/nodes?include=packages \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
{- "object": "list",
- "count": 2,
- "data": [
- {
- "name": "Acme Staffing",
- "custom_id": "zpy8orej4r614ize",
- "tier": "department",
- "parent_custom_id": "2tpiycfpbw5o3xat",
- "packages": [
- "driver_pro",
- "tasker_pro"
]
}
]
}
Candidates represent people who have applied for positions within your company, and have agreed to a background check. Use the Candidate object to collect all Personally Identifiable Information (PII) for a candidate, and all relevant Checkr information, including any generated Reports, or attached Geos.
Creates a new Candidate resource.
The Candidate resource’s required attributes vary depending on its intended use. If this resource is to be used in conjunction with the Invitations API (in which the invitation apply form collects the Candidate's personal information), the only strictly required Candidate attribute is email
.
If this resource is to be used to generate any other report type, other personal information is also required.
Attributes required to generate a Report include:
first_name
middle_name
or no_middle_name
last_name
dob
Attributes required to generate a Report with a criminal check screening:
ssn
zipcode
Attributes required to generate a report with a Motor Vehicle Record (MVR) screening:
driver_license_number
driver_license_state
See Driver License validation in the Reference section for a list of valid input by state.
Attributes recommended to generate a report with an Identity Document Verification screening:
phone
(mobile phone number)Validation for these attributes is performed when requesting a Report, as the requirements depend on the Package.
Checkr's product incorporates SSN field controls designed to not accept SSNs with the following characteristics:
first_name | string[a-zA-Z0-9ªµºÀ-ÖØ-öø-ÿ\-'., ]* Candidate’s first name. |
middle_name | string[a-zA-Z0-9ªµºÀ-ÖØ-öø-ÿ\-'., ]* Candidate’s middle name. This field is required if |
no_middle_name | boolean Default: false Required if no |
last_name | string[a-zA-Z0-9ªµºÀ-ÖØ-öø-ÿ\-'., ]{2,} Candidate’s last name. |
mother_maiden_name | string[a-zA-Z0-9ªµºÀ-ÖØ-öø-ÿ\-'., ]* Candidate’s mother’s maiden name. |
email required | string <email> Candidate’s email address. |
phone | string Nullable Candidate’s phone number. |
zipcode | string Candidate’s 5-digit zip code. |
dob | string <date> Candidate’s date of birth. |
ssn | string Candidate’s Social Security Number. This value will be redacted in all return calls, except for the last four digits. |
driver_license_number | string Candidate’s driver license number. |
driver_license_state | string Candidate’s driver license state of issue.
Format: |
previous_driver_license_number | string Candidate’s previous driver license number. |
previous_driver_license_state | string State that issued the candidate’s previous driver license.
Format: |
copy_requested | boolean Default: false If |
custom_id | string Client-assigned unique ID for the Candidate. Can be used to map Checkr Candidate IDs to your internal tracking system, and to search for Candidates through both the Dashboard and the API. |
geo_ids | Array of strings Array of Geo IDs. |
metadata | object (Metadata) Up to 50 customer-defined key-value pairs. Use this parameter to store additional information on your candidate. For example: Use the key to map candidates to |
Array of objects (WorkLocation) Required for non-US candidates. Array of locations described using country, state, and city. When country is not specified defaults to US. State is required for US candidates. Country is required for non-US candidates. |
$ curl -X POST https://api.checkr.com/v1/candidates \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9: \ -H 'Content-Type: application/json' \ -d '{"first_name":"John", "middle_name":"Alfred", "last_name":"Smith", "email":"john.smith@gmail.com", "phone":"5555555555", "zipcode":"90401", "dob":"1970-01-22", "ssn":"847-43-4645", "driver_license_number":"F2111655", "driver_license_state":"CA", "work_locations":[{"country":"US"}]}'
{- "id": "e44aa283528e6fde7d542194",
- "object": "candidate",
- "uri": "/v1/candidates/e44aa283528e6fde7d542194",
- "first_name": "John",
- "middle_name": "Alfred",
- "no_middle_name": false,
- "last_name": "Smith",
- "mother_maiden_name": "Jones",
- "email": "john.smith@gmail.com",
- "phone": 5555555555,
- "zipcode": 90401,
- "dob": "1970-01-22",
- "ssn": "XXX-XX-4645",
- "driver_license_number": "F2111655",
- "driver_license_state": "CA",
- "previous_driver_license_number": "F1501739",
- "previous_driver_license_state": "MD",
- "copy_requested": false,
- "custom_id": "string",
- "report_ids": [
- "532e71cfe88a1d4e8d00000d"
], - "geo_ids": [
- "79f943e212cce7de21c054a8"
], - "adjudication": "engaged",
- "metadata": { }
}
Lists existing Candidates with the input parameters.
Note: This call will not return candidates with non-US work_locations
. Use GET /candidates/{id} to retrieve candidates outside the US.
string Returns candidates with the input email address. | |
full_name | string Returns candidates with the input |
adjudication | string Returns candidates with the input adjudication. |
custom_id | string Returns candidates with the input |
created_after | string <date-time> Returns candidates created after the input date. |
created_before | string <date-time> Returns candidates created before the input date. |
report_adjudicated_after | string <date-time> Returns candidates adjudicated after the input date. |
report_adjudicated_before | string <date-time> Returns candidates adjudicated before the input date. |
report_adjudicator_email | string Returns candidates with a report adjudicated by someone with input |
report_revised_after | string <date-time> Returns candidates with a report revised after the input date. |
report_revised_before | string <date-time> Returns candidates with a report revised before the input date. |
driver_license_number | string Returns candidates with the input |
geo_id | string Returns candidates with the input |
program_id | string Returns candidates with the input |
metadata | object Returns candidates matching the input key-values. Input keys will be matched exactly. Input values will be pre- and post-pended with wildcards. (For example: A query for 1234 will return results for *1234*.) |
page | number Nullable Specifies the page number to retrieve. |
per_page | number Nullable Indicates how many records each page should contain. The default value is 25 records. |
$ curl -X GET https://api.checkr.com/v1/candidates \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
{- "object": "list",
- "count": 2,
- "data": [
- {
- "id": "e44aa283528e6fde7d542194",
- "object": "candidate",
- "uri": "/v1/candidates/e44aa283528e6fde7d542194",
- "first_name": "John",
- "middle_name": "Alfred",
- "no_middle_name": false,
- "last_name": "Smith",
- "mother_maiden_name": "Jones",
- "email": "john.smith@gmail.com",
- "phone": 5555555555,
- "zipcode": 90401,
- "dob": "1970-01-22",
- "ssn": "XXX-XX-4645",
- "driver_license_number": "F2111655",
- "driver_license_state": "CA",
- "previous_driver_license_number": "F1501739",
- "previous_driver_license_state": "MD",
- "copy_requested": false,
- "custom_id": "string",
- "report_ids": [
- "532e71cfe88a1d4e8d00000d"
], - "geo_ids": [
- "79f943e212cce7de21c054a8"
], - "adjudication": "engaged",
- "metadata": { }
}
]
}
Updates an existing Candidate.
Attempts to update a field that cannot be updated will return a 400 error stating "... cannot be updated”. For example, attempting to update an SSN will return 400 stating "Candidate SSN can not be updated because it has reports”.
Updating geo_ids
will replace all existing Geos. To keep existing geos, include their IDs in the update request. geo_ids
cannot be updated if the candidate's work location is outside the US.
Only fields with null
values can be updated after a Report has been ordered for a Candidate with the exception of the following fields:
Updating metadata with an empty value (null or empty object) will delete existing metadata. Individual keys may also be set and unset.
id required | string The Candidate's ID. |
first_name | string non-empty [a-zA-Z0-9ªµºÀ-ÖØ-öø-ÿ\-'., ]* Candidate’s first name. |
middle_name | string[a-zA-Z0-9ªµºÀ-ÖØ-öø-ÿ\-'., ]* Candidate’s middle name. This field is required if |
no_middle_name | boolean Default: false Required if no |
last_name | string non-empty [a-zA-Z0-9ªµºÀ-ÖØ-öø-ÿ\-'., ]{2,} Candidate’s last name. |
mother_maiden_name | string[a-zA-Z0-9ªµºÀ-ÖØ-öø-ÿ\-'., ]* Candidate’s mother’s maiden name. |
string <email> Candidate’s email address. | |
phone | string Nullable Candidate’s phone number. |
zipcode | string Candidate’s 5-digit zip code. |
dob | string <date> Candidate’s date of birth. |
ssn | string Candidate’s Social Security Number. This value will be redacted in all return calls, except for the last four digits. |
driver_license_number | string Candidate’s driver license number. |
driver_license_state | string Candidate’s driver license state of issue.
Format: |
previous_driver_license_number | string Candidate’s previous driver license number. |
previous_driver_license_state | string State that issued the candidate’s previous driver license.
Format: |
copy_requested | boolean Default: false If |
custom_id | string Client-assigned unique ID for the Candidate. Can be used to map Checkr Candidate IDs to your internal tracking system, and to search for Candidates through both the Dashboard and the API. |
geo_ids | Array of strings Array of Geo IDs. |
adjudication | string The adjudication for the Candidate’s most recently created Report. |
metadata | object (Metadata) Up to 50 customer-defined key-value pairs. Use this parameter to store additional information on your candidate. For example: Use the key to map candidates to |
$ curl -X POST https://api.checkr.com/v1/candidates/e44aa283528e6fde7d542194 \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9: \ -d first_name=John \ -d middle_name=Alfred \ -d last_name=Smith \ -d email=john.smith@gmail.com \ -d phone=5555555555 \ -d zipcode=90401 \ -d dob=1970-01-22 \ -d ssn=543-43-4645 \ -d 'geo_ids[]=87f5bb4983eade22c55f4731&geo_ids[]=22b20140fc1adfae693ca35c'
{- "id": "e44aa283528e6fde7d542194",
- "object": "candidate",
- "uri": "/v1/candidates/e44aa283528e6fde7d542194",
- "first_name": "John",
- "middle_name": "Alfred",
- "no_middle_name": false,
- "last_name": "Smith",
- "mother_maiden_name": "Jones",
- "email": "john.smith@gmail.com",
- "phone": 5555555555,
- "zipcode": 90401,
- "dob": "1970-01-22",
- "ssn": "XXX-XX-4645",
- "driver_license_number": "F2111655",
- "driver_license_state": "CA",
- "previous_driver_license_number": "F1501739",
- "previous_driver_license_state": "MD",
- "copy_requested": false,
- "custom_id": "string",
- "report_ids": [
- "532e71cfe88a1d4e8d00000d"
], - "geo_ids": [
- "79f943e212cce7de21c054a8"
], - "adjudication": "engaged",
- "metadata": { }
}
Retrieves an existing Candidate.
id required | string The Candidate's ID. |
include | string Comma delimited string specifying the resources to be embedded in the returned Candidate object. See Embedding Resources. Example: include=reports,geos |
$ curl -X GET https://api.checkr.com/v1/candidates/e44aa283528e6fde7d542194 \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
{- "id": "e44aa283528e6fde7d542194",
- "object": "candidate",
- "uri": "/v1/candidates/e44aa283528e6fde7d542194",
- "first_name": "John",
- "middle_name": "Alfred",
- "no_middle_name": false,
- "last_name": "Smith",
- "mother_maiden_name": "Jones",
- "email": "john.smith@gmail.com",
- "phone": 5555555555,
- "zipcode": 90401,
- "dob": "1970-01-22",
- "ssn": "XXX-XX-4645",
- "driver_license_number": "F2111655",
- "driver_license_state": "CA",
- "previous_driver_license_number": "F1501739",
- "previous_driver_license_state": "MD",
- "copy_requested": false,
- "custom_id": "string",
- "report_ids": [
- "532e71cfe88a1d4e8d00000d"
], - "geo_ids": [
- "79f943e212cce7de21c054a8"
], - "adjudication": "engaged",
- "metadata": { }
}
Requests the removal of PII from an existing Candidate
Requesting the removal of PII from a candidate who has already had PII removed will result in an error.
id required | string The Candidate's ID. |
deletion_contact_email_address required | string Email address of person requesting candidate's PII removal. |
deletion_contact_first_name | string First name of person requesting candidate's PII removal. |
deletion_contact_last_name | string Last name of person requesting candidate's PII removal. |
{- "deletion_contact_email_address": "john.smith@gmail.com",
- "deletion_contact_first_name": "John",
- "deletion_contact_last_name": "Smith"
}
{- "id": "e44aa283528e6fde7d542194",
- "object": "candidate",
- "uri": "/v1/candidates/e44aa283528e6fde7d542194",
- "first_name": "John",
- "middle_name": "Alfred",
- "no_middle_name": false,
- "last_name": "Smith",
- "mother_maiden_name": "Jones",
- "email": "john.smith@gmail.com",
- "phone": 5555555555,
- "zipcode": 90401,
- "dob": "1970-01-22",
- "ssn": "XXX-XX-4645",
- "driver_license_number": "F2111655",
- "driver_license_state": "CA",
- "previous_driver_license_number": "F1501739",
- "previous_driver_license_state": "MD",
- "copy_requested": false,
- "custom_id": "string",
- "report_ids": [
- "532e71cfe88a1d4e8d00000d"
], - "geo_ids": [
- "79f943e212cce7de21c054a8"
], - "adjudication": "engaged",
- "metadata": { }
}
Reports provide all information relevant to a candidate’s requested background check. Reports include the status of the background check process, the list of searches included in the check, and the Package requested. Depending on the Package selected, a report may include any combination of Checkr Screenings listed below.
Reports are provided to candidates through the Candidate Portal, and as a PDF (if requested).
For more information on the searches listed, see Screenings (below), or Screening Types in the Checkr Help Center.
Creates a new Report resource.
Notes:
/invitations
API to order these reports./reports
API. Please use the /invitations
API to initiate the Checkr-Hosted Apply Flow when ordering background checks that include any of these screening types.candidate_id required | string ID of the Candidate screened. |
package required | string
|
node | string Required for hierarchy-enabled accounts.
|
Array of objects (SelfDisclosure) Array of SelfDisclosures Note: Self Disclosures may not be added, updated, or deleted after a Report has been created. The information provided in a Self Disclosure will not be included in the completed Report, and may be retrieved using GET Removing the requirement for the description, date, and location parameters greatly reduces the value of Self Disclosures. If your system mandates that these parameters be optional, work with your Checkr Customer Success Manager to disable the requirement. | |
Array of objects (WorkLocation) Required for hierarchy-enabled accounts. Array of locations described using country, state, and city. When country is not specified defaults to US. State is required for US candidates. Country is required for non-US candidates. | |
tags | Array of strings Array of tags for the Report. |
$ curl -X POST https://api.checkr.com/v1/reports \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9: \ -d package=driver_pro \ -d candidate_id=e44aa283528e6fde7d542194
{- "id": "e44aa283528e6fde7d542194",
- "object": "report",
- "uri": "/v1/reports/4722c07dd9a10c3985ae432a",
- "status": "complete",
- "result": "clear",
- "includes_canceled": false,
- "created_at": "2014-01-18T12:34:00Z",
- "completed_at": "2014-01-18T12:35:30Z",
- "revised_at": null,
- "upgraded_at": null,
- "turnaround_time": 90,
- "package": "driver_pro",
- "adjudication": "engaged",
- "assessment": "eligible",
- "source": "api",
- "segment_stamps": [
- [
- "unit|Anvil Charlotte",
- "company|Acme Corporation",
- "division|Anvil Sales",
- "region|Anvil South East"
]
], - "work_locations": [
- {
- "country": "US",
- "state": "CA",
- "city": "San Francisco"
}
], - "estimated_completion_time": "2019-07-31T00:00:00Z",
- "candidate_story_ids": [
- "989b4c2d83dd8a81547f2dae"
], - "candidate_id": "e44aa283528e6fde7d542194",
- "drug_screening": {
- "id": "539fd88c101897f7cd000001",
- "status": "clear",
- "result": "clear",
- "disposition": "negative",
- "mro_notes": "Diluted Sample",
- "analytes": [
- {
- "name": "Marijuana",
- "disposition": "negative",
- "specimen_type": "urine"
}
], - "events": [
- {
- "type": "status_update",
- "text": "Specimen Sent to Lab",
- "created_at": "2014-01-19T11:28:31Z"
}
], - "screening_pass_expires_at": "2014-01-19T11:28:31Z",
- "appointment_id": "539fd88c101897f7cd000001"
}, - "ssn_trace_id": "539fd88c101897f7cd000001",
- "arrest_search_id": "539fd88c101897f7cd000001",
- "drug_screening_id": "539fd88c101897f7cd000001",
- "facis_search_id": "539fd88c101897f7cd000001",
- "federal_criminal_search_id": "539fd88c101897f7cd000001",
- "federal_district_criminal_search_id": "539fd88c101897f7cd000001",
- "federal_civil_search_id": "539fd88c101897f7cd000001",
- "federal_district_civil_search_id": "539fd88c101897f7cd000001",
- "global_watchlist_search_id": "539fd88c101897f7cd000001",
- "sex_offender_search_id": "539fd88c101897f7cd000008",
- "national_criminal_search_id": "539fd88c101897f7cd000006",
- "county_criminal_search_ids": [
- "539fdcf335644a0ef4000003"
], - "personal_reference_verification_ids": [
- "539fdcf335644a0ef4000003"
], - "professional_reference_verification_ids": [
- "539fdcf335644a0ef4000003"
], - "motor_vehicle_report_id": "539fd88c101897f7cd000007",
- "professional_license_verification_ids": [
- "5ee1b0c080c74df951ce6a59"
], - "state_criminal_searches": [
- "539fdcf335644a0ef4000003"
], - "international_criminal_searches_v2_ids": [
- "41007c751c9a15c892c0981a0400d1"
], - "international_adverse_media_search_ids": [
- "41007c751c9a15c892c0981a0400e2"
], - "international_global_watchlist_search_id": "41007c751c9a15c892c0981a0400f3",
- "international_education_verification_id": "41007c751c9a15c892c0981a040004",
- "international_employment_verification_id": "41007c751c9a15c892c0981a040015",
- "international_identity_document_validation_id": "41007c751c9a15c892c0981a040026",
- "document_ids": [
- "539fdcf335496a0ef4000003"
], - "geo_ids": [
- "87f5bb4983eade22c55f4731"
], - "program_id": "00166f9ff39ec7b453adfaec"
}
Updates the package
or adjudication
for an existing Report resource.
Use this endpoint to update reports which include the candidate's Social Security Number. To update a Report which does not include an SSN, first use the update Candidate request to add the candidate’s SSN before updating the report.
Either package
or adjudication
is required.
Note: This endpoint may also be used to update international reports for candidates which do not include an SSN.
Note: The Package of a Report cannot be updated if it has an Adverse Action with the status: complete
or dispute
. To proceed, cancel the Adverse Action or create a new Report.
id required | string The Report's ID. |
package | string Slug of the Package. |
adjudication | string Value: "engaged" |
$ curl -X POST https://api.checkr.com/v1/reports/4722c07dd9a10c3985ae432a \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9: \ -d package=driver_pro
{- "id": "e44aa283528e6fde7d542194",
- "object": "report",
- "uri": "/v1/reports/4722c07dd9a10c3985ae432a",
- "status": "complete",
- "result": "clear",
- "includes_canceled": false,
- "created_at": "2014-01-18T12:34:00Z",
- "completed_at": "2014-01-18T12:35:30Z",
- "revised_at": null,
- "upgraded_at": null,
- "turnaround_time": 90,
- "package": "driver_pro",
- "adjudication": "engaged",
- "assessment": "eligible",
- "source": "api",
- "segment_stamps": [
- [
- "unit|Anvil Charlotte",
- "company|Acme Corporation",
- "division|Anvil Sales",
- "region|Anvil South East"
]
], - "work_locations": [
- {
- "country": "US",
- "state": "CA",
- "city": "San Francisco"
}
], - "estimated_completion_time": "2019-07-31T00:00:00Z",
- "candidate_story_ids": [
- "989b4c2d83dd8a81547f2dae"
], - "candidate_id": "e44aa283528e6fde7d542194",
- "drug_screening": {
- "id": "539fd88c101897f7cd000001",
- "status": "clear",
- "result": "clear",
- "disposition": "negative",
- "mro_notes": "Diluted Sample",
- "analytes": [
- {
- "name": "Marijuana",
- "disposition": "negative",
- "specimen_type": "urine"
}
], - "events": [
- {
- "type": "status_update",
- "text": "Specimen Sent to Lab",
- "created_at": "2014-01-19T11:28:31Z"
}
], - "screening_pass_expires_at": "2014-01-19T11:28:31Z",
- "appointment_id": "539fd88c101897f7cd000001"
}, - "ssn_trace_id": "539fd88c101897f7cd000001",
- "arrest_search_id": "539fd88c101897f7cd000001",
- "drug_screening_id": "539fd88c101897f7cd000001",
- "facis_search_id": "539fd88c101897f7cd000001",
- "federal_criminal_search_id": "539fd88c101897f7cd000001",
- "federal_district_criminal_search_id": "539fd88c101897f7cd000001",
- "federal_civil_search_id": "539fd88c101897f7cd000001",
- "federal_district_civil_search_id": "539fd88c101897f7cd000001",
- "global_watchlist_search_id": "539fd88c101897f7cd000001",
- "sex_offender_search_id": "539fd88c101897f7cd000008",
- "national_criminal_search_id": "539fd88c101897f7cd000006",
- "county_criminal_search_ids": [
- "539fdcf335644a0ef4000003"
], - "personal_reference_verification_ids": [
- "539fdcf335644a0ef4000003"
], - "professional_reference_verification_ids": [
- "539fdcf335644a0ef4000003"
], - "motor_vehicle_report_id": "539fd88c101897f7cd000007",
- "professional_license_verification_ids": [
- "5ee1b0c080c74df951ce6a59"
], - "state_criminal_searches": [
- "539fdcf335644a0ef4000003"
], - "international_criminal_searches_v2_ids": [
- "41007c751c9a15c892c0981a0400d1"
], - "international_adverse_media_search_ids": [
- "41007c751c9a15c892c0981a0400e2"
], - "international_global_watchlist_search_id": "41007c751c9a15c892c0981a0400f3",
- "international_education_verification_id": "41007c751c9a15c892c0981a040004",
- "international_employment_verification_id": "41007c751c9a15c892c0981a040015",
- "international_identity_document_validation_id": "41007c751c9a15c892c0981a040026",
- "document_ids": [
- "539fdcf335496a0ef4000003"
], - "geo_ids": [
- "87f5bb4983eade22c55f4731"
], - "program_id": "00166f9ff39ec7b453adfaec"
}
Returns an existing Report with the input ID.
id required | string The Report's ID. |
include | string Comma delimited string specifying the resources to be embedded in the returned Report object. See Embedding Resources. Example: include=candidate,drug_screening |
$ curl -X GET https://api.checkr.com/v1/reports/4722c07dd9a10c3985ae432a?include=drug_screening \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
{- "id": "e44aa283528e6fde7d542194",
- "object": "report",
- "uri": "/v1/reports/4722c07dd9a10c3985ae432a",
- "status": "complete",
- "result": "clear",
- "includes_canceled": false,
- "created_at": "2014-01-18T12:34:00Z",
- "completed_at": "2014-01-18T12:35:30Z",
- "revised_at": null,
- "upgraded_at": null,
- "turnaround_time": 90,
- "package": "driver_pro",
- "adjudication": "engaged",
- "assessment": "eligible",
- "source": "api",
- "segment_stamps": [
- [
- "unit|Anvil Charlotte",
- "company|Acme Corporation",
- "division|Anvil Sales",
- "region|Anvil South East"
]
], - "work_locations": [
- {
- "country": "US",
- "state": "CA",
- "city": "San Francisco"
}
], - "estimated_completion_time": "2019-07-31T00:00:00Z",
- "candidate_story_ids": [
- "989b4c2d83dd8a81547f2dae"
], - "candidate_id": "e44aa283528e6fde7d542194",
- "drug_screening": {
- "id": "539fd88c101897f7cd000001",
- "status": "clear",
- "result": "clear",
- "disposition": "negative",
- "mro_notes": "Diluted Sample",
- "analytes": [
- {
- "name": "Marijuana",
- "disposition": "negative",
- "specimen_type": "urine"
}
], - "events": [
- {
- "type": "status_update",
- "text": "Specimen Sent to Lab",
- "created_at": "2014-01-19T11:28:31Z"
}
], - "screening_pass_expires_at": "2014-01-19T11:28:31Z",
- "appointment_id": "539fd88c101897f7cd000001"
}, - "ssn_trace_id": "539fd88c101897f7cd000001",
- "arrest_search_id": "539fd88c101897f7cd000001",
- "drug_screening_id": "539fd88c101897f7cd000001",
- "facis_search_id": "539fd88c101897f7cd000001",
- "federal_criminal_search_id": "539fd88c101897f7cd000001",
- "federal_district_criminal_search_id": "539fd88c101897f7cd000001",
- "federal_civil_search_id": "539fd88c101897f7cd000001",
- "federal_district_civil_search_id": "539fd88c101897f7cd000001",
- "global_watchlist_search_id": "539fd88c101897f7cd000001",
- "sex_offender_search_id": "539fd88c101897f7cd000008",
- "national_criminal_search_id": "539fd88c101897f7cd000006",
- "county_criminal_search_ids": [
- "539fdcf335644a0ef4000003"
], - "personal_reference_verification_ids": [
- "539fdcf335644a0ef4000003"
], - "professional_reference_verification_ids": [
- "539fdcf335644a0ef4000003"
], - "motor_vehicle_report_id": "539fd88c101897f7cd000007",
- "professional_license_verification_ids": [
- "5ee1b0c080c74df951ce6a59"
], - "state_criminal_searches": [
- "539fdcf335644a0ef4000003"
], - "international_criminal_searches_v2_ids": [
- "41007c751c9a15c892c0981a0400d1"
], - "international_adverse_media_search_ids": [
- "41007c751c9a15c892c0981a0400e2"
], - "international_global_watchlist_search_id": "41007c751c9a15c892c0981a0400f3",
- "international_education_verification_id": "41007c751c9a15c892c0981a040004",
- "international_employment_verification_id": "41007c751c9a15c892c0981a040015",
- "international_identity_document_validation_id": "41007c751c9a15c892c0981a040026",
- "document_ids": [
- "539fdcf335496a0ef4000003"
], - "geo_ids": [
- "87f5bb4983eade22c55f4731"
], - "program_id": "00166f9ff39ec7b453adfaec"
}
Cancels all pending or suspended screenings and completes the report.
Use this endpoint to complete reports which include pending or suspended screenings. If a report is completed with pending or suspended screenings, the following events will be triggered:
status
for all in-progress screenings within the report will be updated to canceled
.report.canceled
webhook will be issued.report.updated
, followed by report.complete
.id required | string The Report's ID. |
$ curl -X POST https://api.checkr.com/v1/reports/4722c07dd9a10c3985ae32a/complete \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9
{- "id": "e44aa283528e6fde7d542194",
- "object": "report",
- "uri": "/v1/reports/4722c07dd9a10c3985ae432a",
- "status": "complete",
- "result": "clear",
- "includes_canceled": false,
- "created_at": "2014-01-18T12:34:00Z",
- "completed_at": "2014-01-18T12:35:30Z",
- "revised_at": null,
- "upgraded_at": null,
- "turnaround_time": 90,
- "package": "driver_pro",
- "adjudication": "engaged",
- "assessment": "eligible",
- "source": "api",
- "segment_stamps": [
- [
- "unit|Anvil Charlotte",
- "company|Acme Corporation",
- "division|Anvil Sales",
- "region|Anvil South East"
]
], - "work_locations": [
- {
- "country": "US",
- "state": "CA",
- "city": "San Francisco"
}
], - "estimated_completion_time": "2019-07-31T00:00:00Z",
- "candidate_story_ids": [
- "989b4c2d83dd8a81547f2dae"
], - "candidate_id": "e44aa283528e6fde7d542194",
- "drug_screening": {
- "id": "539fd88c101897f7cd000001",
- "status": "clear",
- "result": "clear",
- "disposition": "negative",
- "mro_notes": "Diluted Sample",
- "analytes": [
- {
- "name": "Marijuana",
- "disposition": "negative",
- "specimen_type": "urine"
}
], - "events": [
- {
- "type": "status_update",
- "text": "Specimen Sent to Lab",
- "created_at": "2014-01-19T11:28:31Z"
}
], - "screening_pass_expires_at": "2014-01-19T11:28:31Z",
- "appointment_id": "539fd88c101897f7cd000001"
}, - "ssn_trace_id": "539fd88c101897f7cd000001",
- "arrest_search_id": "539fd88c101897f7cd000001",
- "drug_screening_id": "539fd88c101897f7cd000001",
- "facis_search_id": "539fd88c101897f7cd000001",
- "federal_criminal_search_id": "539fd88c101897f7cd000001",
- "federal_district_criminal_search_id": "539fd88c101897f7cd000001",
- "federal_civil_search_id": "539fd88c101897f7cd000001",
- "federal_district_civil_search_id": "539fd88c101897f7cd000001",
- "global_watchlist_search_id": "539fd88c101897f7cd000001",
- "sex_offender_search_id": "539fd88c101897f7cd000008",
- "national_criminal_search_id": "539fd88c101897f7cd000006",
- "county_criminal_search_ids": [
- "539fdcf335644a0ef4000003"
], - "personal_reference_verification_ids": [
- "539fdcf335644a0ef4000003"
], - "professional_reference_verification_ids": [
- "539fdcf335644a0ef4000003"
], - "motor_vehicle_report_id": "539fd88c101897f7cd000007",
- "professional_license_verification_ids": [
- "5ee1b0c080c74df951ce6a59"
], - "state_criminal_searches": [
- "539fdcf335644a0ef4000003"
], - "international_criminal_searches_v2_ids": [
- "41007c751c9a15c892c0981a0400d1"
], - "international_adverse_media_search_ids": [
- "41007c751c9a15c892c0981a0400e2"
], - "international_global_watchlist_search_id": "41007c751c9a15c892c0981a0400f3",
- "international_education_verification_id": "41007c751c9a15c892c0981a040004",
- "international_employment_verification_id": "41007c751c9a15c892c0981a040015",
- "international_identity_document_validation_id": "41007c751c9a15c892c0981a040026",
- "document_ids": [
- "539fdcf335496a0ef4000003"
], - "geo_ids": [
- "87f5bb4983eade22c55f4731"
], - "program_id": "00166f9ff39ec7b453adfaec"
}
Packages are a list of screenings to be run for a report. Work with your Checkr Customer Success representative to define Packages that will best serve your business needs.
Returns a list of all existing Packages.
page | number Nullable Specifies the page number to retrieve. |
per_page | number Nullable Indicates how many records each page should contain. The default value is 25 records. |
$ curl -X GET https://api.checkr.com/v1/packages \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
{- "object": "list",
- "count": 2,
- "data": [
- {
- "id": "e44aa283528e6fde7d542194",
- "object": "package",
- "uri": "/v1/packages/e44aa283528e6fde7d542194",
- "created_at": "2014-01-18T12:34:00Z",
- "deleted_at": "2014-01-18T12:34:00Z",
- "name": "Criminal Pro",
- "slug": "criminal_pro",
- "price": 6500,
- "screenings": [
- {
- "type": "ssn_trace",
- "subtype": null
}
]
}
]
}
Returns an existing Package with the input ID.
id required | string ID of the Package to retrieve. |
$ curl -X GET https://api.checkr.com/v1/packages \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
{- "id": "e44aa283528e6fde7d542194",
- "object": "package",
- "uri": "/v1/packages/e44aa283528e6fde7d542194",
- "created_at": "2014-01-18T12:34:00Z",
- "deleted_at": "2014-01-18T12:34:00Z",
- "name": "Criminal Pro",
- "slug": "criminal_pro",
- "price": 6500,
- "screenings": [
- {
- "type": "ssn_trace",
- "subtype": null
}
]
}
Deletes an existing Package.
id required | string ID of the Package to retrieve. |
$ curl -X DELETE https://api.checkr.com/v1/packages/e44aa283528e6fde7d542194 \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
{- "id": "e44aa283528e6fde7d542194",
- "object": "package",
- "uri": "/v1/packages/e44aa283528e6fde7d542194",
- "created_at": "2014-01-18T12:34:00Z",
- "deleted_at": "2014-01-18T12:34:00Z",
- "name": "Criminal Pro",
- "slug": "criminal_pro",
- "price": 6500,
- "screenings": [
- {
- "type": "ssn_trace",
- "subtype": null
}
]
}
Represents a background check invitation. The candidate will receive an email to submit their information.
Note: By default, the date of expiration is set to 7 days after creation. All invitations expire at 11:59:59pm PDT. This enables candidates to have a full last day to complete their invitation.
Creates a new Invitation resource.
package required | string
|
candidate_id required | string ID of the Candidate for whom the Invitation is created. |
node | string Required for hierarchy-enabled accounts.
|
Array of objects (WorkLocation) Required for hierarchy-enabled accounts. Array of locations described using country, state, and city. When country is not specified defaults to US. State is required for US candidates. Country is required for non-US candidates. | |
tags | Array of strings Array of tags for the Report. |
$ curl -X POST https://api.checkr.com/v1/invitations \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9: \ -H 'Content-Type: application/json' \ -d '{"candidate_id":"e44aa283528e6fde7d542194", "package":"driver_pro", "work_locations":[{"country":"US"}]}'
{- "id": "e44aa283528e6fde7d542194",
- "object": "invitation",
- "uri": "/v1/invitations/e44aa283528e6fde7d542194",
- "status": "pending",
- "created_at": "2015-05-14T17:45:34Z",
- "expires_at": "2015-05-21T17:45:34Z",
- "completed_at": null,
- "deleted_at": null,
- "package": "driver_pro",
- "candidate_id": "551564b7865af96a28b13f36",
- "report_id": null
}
Returns a list of existing Invitations with the input status
or candidate_id
.
If no parameters are passed, returns all Invitations.
If candidate_id
or status
is passed, returns Invitations that match the input parameter.
If both candidate_id
and status
are passed, return Invitations that match both parameters.
Returns 400 if the (optional) status
parameter is not pending
, expired
, or completed
.
Note: This call will not return invitations with non-US work_locations
. Use GET /invitations/{id} to retrieve candidates outside the US.
candidate_id | string ID of the candidate to whom the invitation was issued. |
status | string Status of the Invitation. |
page | number Nullable Specifies the page number to retrieve. |
per_page | number Nullable Indicates how many records each page should contain. The default value is 25 records. |
$ curl -X GET https://api.checkr.com/v1/invitations \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9: \ -d status=pending
{- "object": "list",
- "count": 2,
- "data": [
- {
- "id": "e44aa283528e6fde7d542194",
- "object": "invitation",
- "uri": "/v1/invitations/e44aa283528e6fde7d542194",
- "status": "pending",
- "created_at": "2015-05-14T17:45:34Z",
- "expires_at": "2015-05-21T17:45:34Z",
- "completed_at": null,
- "deleted_at": null,
- "package": "driver_pro",
- "candidate_id": "551564b7865af96a28b13f36",
- "report_id": null
}
]
}
Returns an existing Invitation with the input ID.
id required | string The Invitation's ID. |
include_deleted | boolean Retrieve an invitation that has been deleted |
$ curl -X GET https://api.checkr.com/v1/invitations/3c0a0ca94caaab6ca9634f76 \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
{- "id": "e44aa283528e6fde7d542194",
- "object": "invitation",
- "uri": "/v1/invitations/e44aa283528e6fde7d542194",
- "status": "pending",
- "created_at": "2015-05-14T17:45:34Z",
- "expires_at": "2015-05-21T17:45:34Z",
- "completed_at": null,
- "deleted_at": null,
- "package": "driver_pro",
- "candidate_id": "551564b7865af96a28b13f36",
- "report_id": null
}
Cancels an existing Invitation.
id required | string The Invitation's ID. |
$ curl -X DELETE https://api.checkr.com/v1/invitations/4722c07dd9a10c3985ae432a \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9
{- "id": "e44aa283528e6fde7d542194",
- "object": "invitation",
- "uri": "/v1/invitations/e44aa283528e6fde7d542194",
- "status": "pending",
- "created_at": "2015-05-14T17:45:34Z",
- "expires_at": "2015-05-21T17:45:34Z",
- "completed_at": null,
- "deleted_at": null,
- "package": "driver_pro",
- "candidate_id": "551564b7865af96a28b13f36",
- "report_id": null
}
Creates a new Geo resource.
Note: Attempting to create a new Geo with the same name/state combination will result in an 409 error
name required | string Human-readable name of the Geo. |
state required | string US state for the Geo. |
city | string A major city within the input state. |
$ curl -X POST https://api.checkr.com/v1/geos \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9: \ -d name=San+Francisco \ -d city=San+Francisco \ -d state=CA
{- "id": "e44aa283528e6fde7d542194",
- "object": "geo",
- "uri": "/v1/geos/e44aa283528e6fde7d542194",
- "created_at": "2015-01-18T12:34:00Z",
- "name": "SF CA",
- "city": "San Francisco",
- "state": "CA",
- "deleted_at": null
}
Returns a list of existing Geos with the input name
or state
.
name | string Returns all Geos with the input |
state | string Returns all Geos with the input state. |
page | number Nullable Specifies the page number to retrieve. |
per_page | number Nullable Indicates how many records each page should contain. The default value is 25 records. |
$ curl -X GET https://api.checkr.com/v1/geos \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
{- "object": "list",
- "count": 2,
- "data": [
- {
- "id": "e44aa283528e6fde7d542194",
- "object": "geo",
- "uri": "/v1/geos/e44aa283528e6fde7d542194",
- "created_at": "2015-01-18T12:34:00Z",
- "name": "SF CA",
- "city": "San Francisco",
- "state": "CA",
- "deleted_at": null
}
]
}
Returns an existing Geo with the input ID.
id required | string ID of the Geo. |
$ curl -X GET https://api.checkr.com/v1/geos/e44aa283528e6fde7d542194 \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
{- "id": "e44aa283528e6fde7d542194",
- "object": "geo",
- "uri": "/v1/geos/e44aa283528e6fde7d542194",
- "created_at": "2015-01-18T12:34:00Z",
- "name": "SF CA",
- "city": "San Francisco",
- "state": "CA",
- "deleted_at": null
}
Deletes an existing Geo.
id required | string ID of the Geo. |
$ curl -X DELETE https://api.checkr.com/v1/geos/b719804dc15c655f8529a2f2 \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
{- "id": "e44aa283528e6fde7d542194",
- "object": "geo",
- "uri": "/v1/geos/e44aa283528e6fde7d542194",
- "created_at": "2015-01-18T12:34:00Z",
- "name": "SF CA",
- "city": "San Francisco",
- "state": "CA",
- "deleted_at": null
}
Updates an existing Geo resource with the input city
.
city
can only be added once.
id required | string ID of the Geo. |
city | string Nullable Updates the Geo with the input city. |
$ curl -X POST https://api.checkr.com/v1/geos/b719804dc15c655f8529a2f2 \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9: \ -d city=San+Francisco
{- "id": "e44aa283528e6fde7d542194",
- "object": "geo",
- "uri": "/v1/geos/e44aa283528e6fde7d542194",
- "created_at": "2015-01-18T12:34:00Z",
- "name": "SF CA",
- "city": "San Francisco",
- "state": "CA",
- "deleted_at": null
}
Represents a division of an Account. Programs are typically used to identify clients, cost centers, or departments. A Program may have many Geos and may have many Packages.
Returns a list of existing Programs with the input name
.
name | string Returns Programs with the input |
page | number Nullable Specifies the page number to retrieve. |
per_page | number Nullable Indicates how many records each page should contain. The default value is 25 records. |
$ curl -X GET https://api.checkr.com/v1/programs \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
{- "object": "list",
- "count": 2,
- "data": [
- {
- "id": "e44aa283528e6fde7d542194",
- "object": "program",
- "name": "Program A",
- "created_at": "2017-08-07T16:51:09Z",
- "deleted_at": null,
- "package_ids": [
- "a57a0cd15965a585ff7d5d35"
], - "geo_ids": [
- "cbc37748bc6a45b41af5c3f5"
]
}
]
}
Returns an existing Program with the input ID.
id required | string ID of the Program to retrieve. |
$ curl -X GET https://api.checkr.com/v1/programs/e44aa283528e6fde7d542194 \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
{- "id": "e44aa283528e6fde7d542194",
- "object": "program",
- "name": "Program A",
- "created_at": "2017-08-07T16:51:09Z",
- "deleted_at": null,
- "package_ids": [
- "a57a0cd15965a585ff7d5d35"
], - "geo_ids": [
- "cbc37748bc6a45b41af5c3f5"
]
}
Use this endpoint to return the Assessments for Reports.
Note: Listen to the report.updated
webhook to determine when an Assessment has been applied to a report.
Returns Assessments for an existing Report.
report_id required | string The ID of the associated Report. |
$ curl -X GET https://api.checkr.com/v1/reports/b861a56db1b1b89692dd6118/assessments \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
{- "data": [
- {
- "value": "eligible",
- "created_at": "2014-01-18T12:34:015Z",
- "ruleset": {
- "id": "e44aa283528e6fde7d542194",
- "name": "Ruleset for employees in Arizona",
- "version": {
- "number": 5
}
}, - "results": [
- {
- "value": "eligible",
- "assessed_objects": [
- {
- "object_id": "e44aa283528e6fde7d542194",
- "object_type": "criminal_charge"
}
], - "rule": {
- "name": "Allow dismissed charges rule",
- "type": "lookback_period"
}
}
]
}
], - "object": "list",
- "count": 1
}
Represents a background check subscription. A background report with the Package specified will run at every interval.
Creates a new Subscription.
Notes for International Customers: Subscriptions are not available for reports which include international packages. If your candidate is located outside the US, you may not create a Subscription for them.
package required | string
|
candidate_id required | string ID of the candidate being screened. |
start_date required | string <date> Start date for the subscription. This is the date on which the subscription will begin, and the first time the report will be run. |
interval_count | integer The number of intervals between each recurrent background check. |
interval_unit | string Interval at which the subscription will repeat. |
node | string Required for hierarchy-enabled accounts.
|
Array of objects (WorkLocation) Required for hierarchy-enabled accounts. Array of locations described using country, state, and city. When country is not specified defaults to US. State is required for US candidates. Country is required for non-US candidates. |
$ curl -X POST https://api.checkr.com/v1/subscriptions \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9: \ -d package=driver_pro \ -d start_date=2017-02-10 \ -d interval_unit=month \ -d interval_count=1 \ -d candidate_id=4722c07dd9a10c3985ae432a
{- "id": "e44aa283528e6fde7d542194",
- "object": "subscription",
- "uri": "/v1/subscriptions/e44aa283528e6fde7d542194",
- "status": "active",
- "created_at": "2014-01-18T12:34:00Z",
- "canceled_at": null,
- "package": "driver_pro",
- "interval_count": 1,
- "interval_unit": "month",
- "start_date": "2014-06-10",
- "next_occurrence_date": "2014-07-10",
- "candidate_id": "4722c07dd9a10c3985ae432a",
- "node": "zpy8orej4r614ize",
- "work_locations": [
- {
- "country": "US",
- "state": "CA",
- "city": "San Francisco"
}
]
}
Lists existing Subscriptions with the input parameters.
candidate_id | string ID of the candidate to search for subscriptions. |
created_after | string <date-time> Returns subscriptions created after the input date. |
created_before | string <date-time> Returns subscriptions created before the input date. |
status | string Returns subscriptions with the input status. |
page | number Nullable Specifies the page number to retrieve. |
per_page | number Nullable Indicates how many records each page should contain. The default value is 25 records. |
$ curl -X GET https://api.checkr.com/v1/subscriptions \ -d candidate_id=4722c07dd9a10c3985ae432a -d created_after=2021-12-21 -d created_before=2021-12-31 -d status=active -d page=2 -d per_page=10
{- "object": "list",
- "count": 2,
- "data": [
- {
- "id": "e44aa283528e6fde7d542194",
- "object": "subscription",
- "uri": "/v1/subscriptions/e44aa283528e6fde7d542194",
- "status": "active",
- "created_at": "2014-01-18T12:34:00Z",
- "canceled_at": null,
- "package": "driver_pro",
- "interval_count": 1,
- "interval_unit": "month",
- "start_date": "2014-06-10",
- "next_occurrence_date": "2014-07-10",
- "candidate_id": "4722c07dd9a10c3985ae432a",
- "node": "zpy8orej4r614ize",
- "work_locations": [
- {
- "country": "US",
- "state": "CA",
- "city": "San Francisco"
}
]
}
]
}
Retrieves an existing Subscription.
id required | string ID of the Subscription. |
$ curl -X GET https://api.checkr.com/v1/subscriptions/e44aa283528e6fde7d542194 \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
{- "id": "e44aa283528e6fde7d542194",
- "object": "subscription",
- "uri": "/v1/subscriptions/e44aa283528e6fde7d542194",
- "status": "active",
- "created_at": "2014-01-18T12:34:00Z",
- "canceled_at": null,
- "package": "driver_pro",
- "interval_count": 1,
- "interval_unit": "month",
- "start_date": "2014-06-10",
- "next_occurrence_date": "2014-07-10",
- "candidate_id": "4722c07dd9a10c3985ae432a",
- "node": "zpy8orej4r614ize",
- "work_locations": [
- {
- "country": "US",
- "state": "CA",
- "city": "San Francisco"
}
]
}
Updates a Subscription. Specify only those parameters you wish to change.
id required | string ID of the Subscription. |
package | string Package to run for the Report. |
candidate_id | string ID of the candidate being screened. |
start_date | string <date> Start date for the subscription. This is the date on which the subscription will begin, and the first time the report will be run. |
interval_count | integer The number of intervals between each recurrent background check. |
interval_unit | string Interval at which the subscription will repeat. |
node | string
|
Array of objects (WorkLocation) Array of locations described using country, state, and city. When country is not specified defaults to US. State is required for US candidates. Country is required for non-US candidates. |
$ curl -X POST https://api.checkr.com/v1/subscriptions/e44aa283528e6fde7d542194 \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9: \ -d package=driver_pro \ -d start_date=2017-02-10 \ -d interval_unit=month \ -d interval_count=1 \ -d candidate_id=e44aa283528e6fde7d542194
{- "id": "e44aa283528e6fde7d542194",
- "object": "subscription",
- "uri": "/v1/subscriptions/e44aa283528e6fde7d542194",
- "status": "active",
- "created_at": "2014-01-18T12:34:00Z",
- "canceled_at": null,
- "package": "driver_pro",
- "interval_count": 1,
- "interval_unit": "month",
- "start_date": "2014-06-10",
- "next_occurrence_date": "2014-07-10",
- "candidate_id": "4722c07dd9a10c3985ae432a",
- "node": "zpy8orej4r614ize",
- "work_locations": [
- {
- "country": "US",
- "state": "CA",
- "city": "San Francisco"
}
]
}
Cancels an existing Subscription.
id required | string ID of the Subscription. |
$ curl -X DELETE https://api.checkr.com/v1/subscriptions/e44aa283528e6fde7d542194 \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
{- "id": "e44aa283528e6fde7d542194",
- "object": "subscription",
- "uri": "/v1/subscriptions/4722c07dd9a10c3985ae432a",
- "status": "active",
- "created_at": "2014-01-18T12:34:00Z",
- "canceled_at": "2014-01-30T12:34:00Z",
- "package": "driver_pro",
- "interval_count": 1,
- "interval_unit": "month",
- "start_date": "2014-06-10",
- "candidate_id": "e44aa283528e6fde7d542194"
}
Continuous Check runs a monthly check for pointers to new records, which may result in a Report. Unlike a Subscription, which generates a full Report at a defined cadence, Continuous Check generates a full Report only if new reportable information is found. For more information, see Continuous Crim: The new standard of safety and Continuous MVR: The new standard in driver safety in the Checkr Help Center.
Use the report.complete
webhook to watch for new Reports created for candidates enrolled in Continuous Check. These Reports will list one of the following as the Package within the webhook payload:
continuous_check
continuous_mvr
continuous_mvr_enrollment
Note: These Package names are returned through the Checkr APIs, but may not be used as input. Attempting to create Invitations, Reports, or Subscriptions with these Packages will result in a Package not found
error.
Note: It is your legal obligation to manage your list of candidates enrolled in Continuous Check. You must obtain the required evergreen consent before enrolling them, and you must remove them from the service when they begin an Adverse Action process or are removed from your platform. Work with your legal counsel to ensure that your Continuous Check process remains compliant with all applicable laws and regulations.
Note: If your candidate is located outside of the US, they cannot be enrolled in Continuous Check.
Creates a new Continuous Check resource.
candidate_id required | string The Candidate's ID. |
type required | string Defines the screening type(s) for this Continuous Check. |
node | string Required for hierarchy-enabled accounts with Nodes.
|
Array of objects (WorkLocation) Required for hierarchy-enabled accounts. Array of locations described using country, state, and city. When country is not specified defaults to US. State is required for US candidates. Country is required for non-US candidates. |
$ curl -X POST https://api.checkr.com/v1/candidates/e44aa283528e6fde7d542194/continuous_checks \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9: \ -d type=criminal
{- "id": "e44aa283528e6fde7d542194",
- "object": "continuous_check",
- "type": "criminal",
- "created_at": "2015-05-14T17:45:34Z",
- "candidate_id": "551564b7865af96a28b13f36",
- "node": "zpy8orej4r614ize",
- "work_locations": [
- {
- "country": "US",
- "state": "CA",
- "city": "San Francisco"
}
]
}
Returns a list of existing Continuous Checks.
candidate_id required | string The Candidate's ID. |
$ curl -X GET https://api.checkr.com/v1/candidates/e44aa283528e6fde7d542194/continuous_checks \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
{- "data": [
- {
- "id": "e44aa283528e6fde7d542194",
- "object": "continuous_check",
- "type": "criminal",
- "created_at": "2015-05-14T17:45:34Z",
- "candidate_id": "551564b7865af96a28b13f36",
- "node": "zpy8orej4r614ize",
- "work_locations": [
- {
- "country": "US",
- "state": "CA",
- "city": "San Francisco"
}
]
}
], - "object": "list",
- "count": 1
}
Returns an existing Continuous Check with the input ID.
id required | string The Continuous Check's ID. |
$ curl -X GET https://api.checkr.com/v1/continuous_checks/4722c07dd9a10c3985ae432a \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
{- "id": "e44aa283528e6fde7d542194",
- "object": "continuous_check",
- "type": "criminal",
- "created_at": "2015-05-14T17:45:34Z",
- "candidate_id": "551564b7865af96a28b13f36",
- "node": "zpy8orej4r614ize",
- "work_locations": [
- {
- "country": "US",
- "state": "CA",
- "city": "San Francisco"
}
]
}
Updates the node and/or work locations of an existing Continuous Check.
id required | string The Continuous Check's ID. |
node | string
|
Array of objects (WorkLocation) Array of locations described using country, state, and city. When country is not specified defaults to US. State is required for US candidates. Country is required for non-US candidates. |
$ curl -X POST https://api.checkr.com/v1/continuous_checks/76c7435e035d43b55bb9d1c6 \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9: \ -d node=zpy8orej4r614ize
{- "id": "e44aa283528e6fde7d542194",
- "object": "continuous_check",
- "type": "criminal",
- "created_at": "2015-05-14T17:45:34Z",
- "candidate_id": "551564b7865af96a28b13f36",
- "node": "zpy8orej4r614ize",
- "work_locations": [
- {
- "country": "US",
- "state": "CA",
- "city": "San Francisco"
}
]
}
Cancels an existing Continuous Check.
id required | string The Continuous Check's ID. |
$ curl -X DELETE https://api.checkr.com/v1/continuous_checks/4722c07dd9a10c3985ae432a \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9
{- "id": "e44aa283528e6fde7d542194",
- "object": "continuous_check",
- "type": "criminal",
- "created_at": "2015-05-14T17:45:34Z",
- "candidate_id": "551564b7865af96a28b13f36",
- "node": "zpy8orej4r614ize",
- "work_locations": [
- {
- "country": "US",
- "state": "CA",
- "city": "San Francisco"
}
]
}
Adverse Actions are initiated by Checkr customers if something is returned on a Candidate’s report that requires further investigation. When an Adverse Action is initiated, the candidate must be informed, and given time to address the issues raised.
National and local laws control the Adverse Action process and define the sequence and timing with which it must process. Please work with your legal council to ensure that your process is compliant.
For more information, see The Adverse Actions Process in the Checkr Help Center.
Returns an existing Adverse Action with the input ID.
id required | string ID of the Adverse Action. |
$ curl -X GET https://api.checkr.com/v1/adverse_actions/57ed51e57619e8002a6683f2 \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
{- "id": "e44aa283528e6fde7d542194",
- "object": "adverse_action",
- "uri": "/v1/adverse_actions/57ed51e57619e8002a6683f2",
- "created_at": "2016-09-29T17:39:49Z",
- "status": "pending",
- "report_id": "b861a56db1b1b89692dd6118",
- "post_notice_scheduled_at": "2016-10-07T12:34:00Z",
- "post_notice_ready_at": "2016-10-06T17:39:48Z",
- "canceled_at": null,
- "adverse_items": [
- {
- "id": "e44aa283528e6fde7d542194",
- "object": "adverse_item",
- "text": "License status: Suspended",
- "assessment": {
- "value": "eligible",
- "rule": {
- "name": "Allow dismissed charges rule",
- "type": "lookback_period"
}
}
}
], - "individualized_assessment_engaged": false
}
Cancels an existing Adverse Action.
id required | string ID of the Adverse Action. |
$ curl -X DELETE https://api.checkr.com/v1/adverse_actions/e44aa283528e6fdaa9542194 \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
{- "id": "e44aa283528e6fde7d542194",
- "object": "adverse_action",
- "uri": "/v1/adverse_actions/57ed51e57619e8002a6683f2",
- "created_at": "2016-09-29T17:39:49Z",
- "status": "pending",
- "report_id": "b861a56db1b1b89692dd6118",
- "post_notice_scheduled_at": "2016-10-07T12:34:00Z",
- "post_notice_ready_at": "2016-10-06T17:39:48Z",
- "canceled_at": null,
- "adverse_items": [
- {
- "id": "e44aa283528e6fde7d542194",
- "object": "adverse_item",
- "text": "License status: Suspended",
- "assessment": {
- "value": "eligible",
- "rule": {
- "name": "Allow dismissed charges rule",
- "type": "lookback_period"
}
}
}
], - "individualized_assessment_engaged": false
}
Creates a new Adverse Action.
Note: Report must be in a consider
status and cannot have any existing Adverse Actions that have not been canceled.
report_id required | string The ID of the Report for which the Adverse Action will be created. |
post_notice_scheduled_at | string <date-time> Time at which the Post-Adverse Action notification will be sent. Default is 7 days after creation. |
adverse_item_ids required | Array of strings IDs of Adverse Items selected for the Adverse Action. |
$ curl -X POST https://api.checkr.com/v1/reports/b861a56db1b1b89692dd6118/adverse_actions \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9: \ -d post_notice_scheduled_at=2016-10-07T12:34:00Z \ -d 'adverse_item_ids[]=57ed4ce3057e0b002adc6d90&adverse_item_ids[]=57ed4ce3057e0b002adc6d91'
{- "id": "e44aa283528e6fde7d542194",
- "object": "adverse_action",
- "uri": "/v1/adverse_actions/57ed51e57619e8002a6683f2",
- "created_at": "2016-09-29T17:39:49Z",
- "status": "pending",
- "report_id": "b861a56db1b1b89692dd6118",
- "post_notice_scheduled_at": "2016-10-07T12:34:00Z",
- "post_notice_ready_at": "2016-10-06T17:39:48Z",
- "canceled_at": null,
- "adverse_items": [
- {
- "id": "e44aa283528e6fde7d542194",
- "object": "adverse_item",
- "text": "License status: Suspended",
- "assessment": {
- "value": "eligible",
- "rule": {
- "name": "Allow dismissed charges rule",
- "type": "lookback_period"
}
}
}
], - "individualized_assessment_engaged": false
}
Adverse Items are items selected from a returned report that may be used to initiate Adverse Action for a Candidate.
Returns a list of existing Adverse Items with the input report_id
.
Note: Report must be in a consider
status and cannot have any existing Adverse Actions that have not been canceled.
Returns 400 if the Report's status is not Consider or the Report already has an active (non-cancelled) Adverse Action.
report_id required | string The ID of the associated Report. |
$ curl -X GET https://api.checkr.com/v1/reports/b861a56db1b1b89692dd6118/adverse_items \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
{- "data": [
- {
- "id": "e44aa283528e6fde7d542194",
- "object": "adverse_item",
- "text": "License status: Suspended",
- "assessment": {
- "value": "eligible",
- "rule": {
- "name": "Allow dismissed charges rule",
- "type": "lookback_period"
}
}
}
], - "object": "list",
- "count": 1
}
Represents a link by which candidates may upload a document. If a candidate must upload
documents to continue processing their report, a set of Verifications will be available.
Checkr offers two verification types: id
and education
. ID Verifications are used for
identity and license purposes, such as ID card or driver’s license. Education Verifications
are used for documents related to Education Verification.
Returns a list of existing Verifications for the input report_id
.
report_id required | string Returns the list of verifications for the input |
$ curl -X GET https://api.checkr.com/v1/reports/4722c07dd9a10c3985ae432a/verifications \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
{- "data": [
- {
- "id": "e44aa283528e6fde7d542194",
- "object": "verification",
- "uri": "/v1/verifications/db313e73383710d4fa2f18fd",
- "created_at": "2014-01-18T12:34:00Z",
- "completed_at": null,
- "processed_at": null,
- "verification_type": "id",
- "report_id": "4722c07dd9a10c3985ae432a"
}
], - "object": "list",
- "count": 2
}
Returns an existing Verification with the input ID
verification_id required | string |
$ curl -X GET https://api.checkr.com/v1/verifications/db313e73383710d4fa2f18fd \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
{- "id": "e44aa283528e6fde7d542194",
- "object": "verification",
- "uri": "/v1/verifications/db313e73383710d4fa2f18fd",
- "created_at": "2014-01-18T12:34:00Z",
- "completed_at": null,
- "processed_at": null,
- "verification_type": "id",
- "report_id": "4722c07dd9a10c3985ae432a"
}
Represents a Document, either related to a Report (such as a PDF Report) or related to a Candidate (such as a Driver License image, or a consent form). Report Document IDs can be retrieved from the Retrieve an existing Report endpoint. Candidate Document IDs can be retrieved using the List a Candidate's Documents endpoint.
Use GET /v1/reports/{id}?include=documents
to return a Report resource that includes an array of document
objects.
Report Documents are of the following types: drug_screen_donor_pass
,
health_screening_occupational_health_document
,
health_screening_result_certificate
, pdf_credit_report
",
pdf_health_report
, pdf_individualized_assessment
, pdf_report
,
pdf_report_encrypted
, pdf_self_disclosure
, pdf_wisconsin_doj
, and
screening_pass
.
Returns an array of candidate-provided Documents for the input candidate_id
.
candidate_id required | string ID of the Candidate for whom documents will be retrieved. |
types | Array of strings The type of candidate-provided document to return. If |
$ curl -X GET https://api.checkr.com/v1/candidates/e44aa283528e6fde7d542194/documents/ \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
{- "data": [
- {
- "id": "e44aa283528e6fde7d542194",
- "object": "document",
- "type": "driver_license",
- "created_at": "2015-02-11T20:01:50Z",
- "filesize": 8576,
- "filename": "1423684910_candidate_driver_license.jpg",
- "content_type": "image/jpeg"
}
], - "object": "list",
- "count": 1
}
Uploads a new Candidate Document.
candidate_id required | string Upload a document for the input |
type required | string Values include: "alien_id" "consent" "citizenship_certificate" "credit_report_consent_form" "driver_license" "driver_license_back" "driver_license_history" "education_proof" "electronic_consent_form" "employment_proof" "government_id" "international_consent_form" "military_id" "national_id" "national_id_back" "passport" "passport_signature_page" "previous_driver_license" "professional_license_certification_image" "selfie" "ssn_card" "state_id_card" "state_id_card_back" "student_id" "taxpayer_id" |
file required | string <binary> Path to the document on your local file system. Valid MIME types: |
$ curl -X POST https://api.checkr.com/v1/candidates/e44aa283528e6fde7d542194/documents \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9: \ --form type=driver_license \ --form file=@candidate_driver_license.jpg
{- "id": "e44aa283528e6fde7d542194",
- "object": "document",
- "type": "driver_license",
- "created_at": "2015-02-11T20:01:50Z",
- "filesize": 8576,
- "filename": "1423684910_candidate_driver_license.jpg",
- "content_type": "image/jpeg"
}
Returns an existing Document with the input ID.
Report Document IDs can be retrieved from the Retrieve an existing Report endpoint. Candidate Document IDs can be retrieved using the List a Candidate's Documents endpoint.
id required | string ID of the Document to retrieve. |
$ curl -X GET https://api.checkr.com/v1/documents/b73f89e14b393979857806f9 \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
{- "id": "e44aa283528e6fde7d542194",
- "object": "document",
- "type": "driver_license",
- "created_at": "2015-02-11T20:01:50Z",
- "filesize": 8576,
- "filename": "1423684910_candidate_driver_license.jpg",
- "content_type": "image/jpeg"
}
The driver licenses resource represents a single driver license for a candidate. Candidates may have one current driver license and may have any number of previous driver licenses.
Creates a new Driver License for a given candidate.
If a current
driver license is created for a candidate with an existing driver license marked current
, the existing license will be updated to reflect that it is no longer current
.
If a candidate_driver_license
exists with the state
and number
passed in with the POST request, a new license will not be created. The current
and issued_date
values of the existing license will be updated with on the parameters passed.
Note: When a new driver license is created, Checkr will attempt to apply the new license information to resolve any existing exceptions for the candidate's most recent MVR screening if the screening has not yet produced reportable results.
See Driver License validation in the Reference section for a list of valid driver license number input by state.
candidate_id required | string The Candidate's ID. |
number required | string The driver license number. |
state required | string The state that issued the driver license. |
issued_date | string <date> The issued date of the driver license. |
current required | boolean Defines whether the driver license is the candidate's current license. |
$ curl -X POST https://api.checkr.com/v1/candidates/5fb31d36bc2e7f4609aba03d/driver_licenses \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9: \ -d number=F2222222 \ -d state=CA \ -d issued_date=2010-01-30 \ -d current=true
{- "id": "e44aa283528e6fde7d542194",
- "object": "candidate_driver_license",
- "uri": "/v1/candidates/551564b7865af96a28b13f36/driver_licenses/e44aa283528e6fde7d542194",
- "candidate_id": "551564b7865af96a28b13f36",
- "number": "F2222222",
- "state": "CA",
- "issued_dates": [
- {
- "value": "2010-01-30",
- "source": "client"
}
], - "current": true
}
Returns a list of existing Driver Licenses for the input Candidate ID.
candidate_id required | string The Candidate's ID. |
$ curl -X GET https://api.checkr.com/v1/candidates/5fb31d36bc2e7f4609aba03d/driver_licenses \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
{- "data": [
- {
- "id": "e44aa283528e6fde7d542194",
- "object": "candidate_driver_license",
- "uri": "/v1/candidates/551564b7865af96a28b13f36/driver_licenses/e44aa283528e6fde7d542194",
- "candidate_id": "551564b7865af96a28b13f36",
- "number": "F2222222",
- "state": "CA",
- "issued_dates": [
- {
- "value": "2010-01-30",
- "source": "client"
}
], - "current": true
}
], - "object": "list",
- "count": 1
}
Returns a specific driver license for a given candidate.
driver_license_id required | string The Driver License ID. |
candidate_id required | string The Candidate's ID. |
$ curl -X GET https://api.checkr.com/v1/candidates/5fb31d36bc2e7f4609aba03d/driver_licenses/505fe6ed108621f9342c4eff \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
{- "id": "e44aa283528e6fde7d542194",
- "object": "candidate_driver_license",
- "uri": "/v1/candidates/551564b7865af96a28b13f36/driver_licenses/e44aa283528e6fde7d542194",
- "candidate_id": "551564b7865af96a28b13f36",
- "number": "F2222222",
- "state": "CA",
- "issued_dates": [
- {
- "value": "2010-01-30",
- "source": "client"
}
], - "current": true
}
Updates an existing Driver License for a given candidate.
Note: Updating an existing license to current: true
will set any existing current
license to current: false
.
driver_license_id required | string The Driver License ID. |
candidate_id required | string The Candidate's ID. |
number | string The updated number of the driver license. |
state | string The updated state that issued the driver license. |
issued_date | string <date> The updated issued date of the driver license. |
current | boolean The updated current status of the driver license. |
$ curl -X POST https://api.checkr.com/v1/candidates/5fb31d36bc2e7f4609aba03d/driver_licenses/76c7435e035d43b55bb9d1c6 \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9: \ -d number=F2222222 \ -d current=true
{- "id": "e44aa283528e6fde7d542194",
- "object": "candidate_driver_license",
- "uri": "/v1/candidates/551564b7865af96a28b13f36/driver_licenses/e44aa283528e6fde7d542194",
- "candidate_id": "551564b7865af96a28b13f36",
- "number": "F2222222",
- "state": "CA",
- "issued_dates": [
- {
- "value": "2010-01-30",
- "source": "client"
}
], - "current": true
}