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 information about using the Checkr Dashboard, and compliance and regulatory aspects of background checks, visit 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 information about using the Checkr Dashboard, and compliance and regulatory aspects of background checks, visit 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 result update of Clear or Consider through their selected method of API webhooks, email, or Checkr Dashboard notifications.
Clear and Consider are the default results. A Clear result can be interpreted as that report having no items listed on the candidate’s record that require consideration. A report with a result 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 staging 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 Requesting a Staging Account in Getting Started.
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 the self-hosted flow offers more control over the background check experience, this needs to be weighed against the burden of having to be responsible for maintaining compliance when presenting the background check disclosure and consent forms, which is not a trivial undertaking. Typically, the self-hosted flow works best for our larger customers that have a dedicated legal department that can provide ongoing monitoring of the changing compliance landscape for background checks. Please see the Creating a fully custom apply flow section for more detail on this.
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.
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, 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 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.
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 Requesting a Staging Account 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.
Subscribing to webhooks is the recommended approach for accessing the report information and status, since it provides near real-time updates and frees the customer from having to poll our API for this information.
$ curl -X GET https://api.checkr.com/v1/reports/a13f4827d8711ddc75abc56ct
While Checkr recommends listening to the report.completed webhook to retrieve the results of a report, you can also retrieve the same information by performing a GET request to the specific URL of the report.
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": [],
"drug_alcohol_clearinghouse_id": "5b64c62b67abb4002d3ec763",
"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.
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. 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 |
---|---|---|
HTTPS |
https://(<user>:<password>@)<hostname>/<path> E.g.: https://notify.company.com/checkr |
Notes: The endpoint to be reached must be public. Webhook URLs 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. |
{
"id": "58f8e550d991bb000db04005",
"object": "event",
"type": "formI9.updated",
"created_at": "2023-11-20T16:44:00Z",
"data": {
"object": {
"id": "c373384e71a9a02098cb7421",
"object": "formI9",
"uri": "/v1/i9/forms_i9/e44aa283528e6fde7d542194",
"candidate_id": "3ae7e278beb24d14a3785e2dd02cca49",
"event_timestamp": "2023-11-20T16:44:00Z",
"status": "section_1_completed"
},
},
}
Event | Description |
---|---|
form_i9.created |
A new Form I9 has been created. |
form_i9.updated |
A in progress Form I9 has received an update. This update will usually mean a change in the section of the report e.g section 1 is signed by a candidate or employee. It can also mean, for those forms created with a worksite that has E-Verify enabled, a change in the E-Verify status. You can find information about Form I-9 statuses in the Form I-9 reference section |
form_i9.completed |
A Form I9 has been completed. |
form_i9.deleted |
A Form I9 has been deleted. |
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
Note: if you generate your RSA key via an alternative method, we require a key size of at least 4096 bits for access to production SSN data.
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.
$ 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: 1200
< 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 1200 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.
409
HTTP status code will be received when another request with the same idempotency key is still being processed. Wait for the other request to complete before making a new request with the same idempotency key.
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.
Workflow types are high-level flows the employee can select at the moment of creating an I9 form, it affects what will be the filling experience is from a candidate’s perspective.
Workflow Type | Description |
---|---|
remote_section_1_only |
Employee will complete Section 1 on their own. Then Employer help them complete Section 2 on-site. |
employer_appointment |
Employee will complete Section 1 on their own. Then Employer authorize a representative to help them complete Section 2. |
employee_appointment |
Employee will complete Section 1 on their own. Then Employer authorize an employee-designated representative to help them complete Section 2. |
Represents the current status of the I-9/e-Verify process.
Status | Description |
---|---|
section_1_incomplete |
Indicates that the employee must complete Section 1. |
section_2_incomplete |
Indicates that the employer/customer or the Authorized Representative (when applicable) must complete Section 2. |
awaiting_approval |
Indicates that the Authorized Representative has completed Section 2 and the employer/customer must review and approve the I-9. |
everify_pending |
Indicates that the e-Verify process is in progress. |
everify_tnc_issued |
Indicates a Tentative Non-Confirmation (TNC) e-Verify status, which requires action from the employer/customer. |
i9_complete |
Indicates that the I-9/e-Verify process is complete. |
Represents tasks that must be completed by the employer/customer.
Status | Description |
---|---|
no_action |
Indicates that there is no action to be taken by the employer/customer. |
complete_section_2 |
Indicates that the employer/customer must complete Section 2. |
appoint_section_2_representative |
Indicates that the employer/customer must appoint an Authorized Representative to complete Section 2. |
accept_reject_i9 |
Indicates that the employer/customer must accept or reject the I-9 after the Authorized Representative has completed Section 2. |
check_user_email |
Indicates that the employer/customer must check the employee's email address as a follow-up action to an e-Verify Tentative Non-Confirmation (TNC) case. |
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_missing_consent | Candidate consent not provided |
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 |
adverse_action_completed | Adverse Action completed prior to screening completion |
adverse_action_suspended_report_timer_customer_requested | Customer configured the Adverse Action on Suspended Reports feature and its timer expired prior to screening completion |
unable_to_fulfill_mvr | Unable to fulfill MVR request as data is not available |
identity_verification_unverified | Identity Verification completed with an Unverified Result and action was taken to cancel the Report |
request_withdrawn | Request withdrawn |
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",
- "account_deauthorization": {
- "reason": "nonpayment"
}, - "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",
- "account_deauthorization": {
- "reason": "nonpayment"
}, - "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"
}
The User resource includes user information and role assignments. Users can be invited and assigned roles from the Dashboard.
Returns a list of all existing Users.
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/users \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
{- "object": "list",
- "count": 2,
- "data": [
- {
- "id": "e44aa283528e6fde7d542194",
- "email": "john.smith@example.com",
- "full_name": "John Smith",
- "created_at": "2014-01-18T12:34:00Z",
- "roles": [
- {
- "name": "admin"
}
]
}
]
}
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 arranged in order as specified by the 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"
]
}
]
}
Returns an existing node by custom_id.
include=packages
is passed, 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.include=packages
is not passed, no package information will be included in the response.custom_id required | string custom_id of the Node. |
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 |
$ curl https://api.checkr.com/v1/nodes/my_custom_id?include=packages \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
{- "name": "Acme Staffing",
- "custom_id": "zpy8orej4r614ize",
- "tier": "department",
- "parent_custom_id": "parent custom id",
- "packages": [
- "driver_pro",
- "tasker_pro"
]
}
Updates the name and tier on an existing node by custom_id.
custom_id required | string custom_id of the Node. |
$ curl -X PATCH https://api.checkr.com/v1/nodes/my_custom_id \ -H 'Content-Type: application/json' \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9: \ -d '{"name":"Acme Staffing", "tier": "department"}'
{- "name": "Acme Staffing",
- "custom_id": "zpy8orej4r614ize",
- "tier": "department",
- "parent_custom_id": "parent custom id",
- "packages": [
- "driver_pro",
- "tasker_pro"
]
}
Deletes an existing node by custom_id.
Parent nodes and nodes assigned to continuous check subscriptions or legacy subscriptions cannot be deleted.
custom_id required | string custom_id of the Node. |
$ curl -X DELETE https://api.checkr.com/v1/nodes/my_custom_id \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
{- "name": "Acme Staffing",
- "custom_id": "zpy8orej4r614ize",
- "tier": "department",
- "parent_custom_id": "parent custom id",
- "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 |
postal_address | object The candidate postal address is the address Checkr will use to send postal mail to the candidate. Each candidate can be associated with only one postal address. |
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"}], "postal_address": { "name": "John Alfred Smith", "street": "123 Main Street", "street2": "APT A", "city": "San Francisco", "state": "CA", "zipcode": "90401" } }'
{- "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",
- "postal_address": {
- "name": "John Alfred Smith",
- "street": "123 Main Street",
- "street2": "APT A",
- "city": "San Francisco",
- "state": "CA",
- "zipcode": "94108"
}, - "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",
- "postal_address": {
- "name": "John Alfred Smith",
- "street": "123 Main Street",
- "street2": "APT A",
- "city": "San Francisco",
- "state": "CA",
- "zipcode": "94108"
}, - "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. |
postal_address | object Candidate's postal address. |
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",
- "postal_address": {
- "name": "John Alfred Smith",
- "street": "123 Main Street",
- "street2": "APT A",
- "city": "San Francisco",
- "state": "CA",
- "zipcode": "94108"
}, - "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",
- "postal_address": {
- "name": "John Alfred Smith",
- "street": "123 Main Street",
- "street2": "APT A",
- "city": "San Francisco",
- "state": "CA",
- "zipcode": "94108"
}, - "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",
- "postal_address": {
- "name": "John Alfred Smith",
- "street": "123 Main Street",
- "street2": "APT A",
- "city": "San Francisco",
- "state": "CA",
- "zipcode": "94108"
}, - "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_alcohol_clearinghouse_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"
], - "occupational_health_screening_id": "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",
- "archived": false
}
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_alcohol_clearinghouse_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"
], - "occupational_health_screening_id": "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",
- "archived": false
}
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_alcohol_clearinghouse_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"
], - "occupational_health_screening_id": "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",
- "archived": false
}
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_alcohol_clearinghouse_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"
], - "occupational_health_screening_id": "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",
- "archived": false
}
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,
- "archived": false,
- "archived_info": {
- "time": "2023-08-29T23:15:34Z",
- "user": {
- "email": "john.smith@gmail.com",
- "id": "1234abcd5678"
}
}
}
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,
- "archived": false,
- "archived_info": {
- "time": "2023-08-29T23:15:34Z",
- "user": {
- "email": "john.smith@gmail.com",
- "id": "1234abcd5678"
}
}
}
]
}
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,
- "archived": false,
- "archived_info": {
- "time": "2023-08-29T23:15:34Z",
- "user": {
- "email": "john.smith@gmail.com",
- "id": "1234abcd5678"
}
}
}
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,
- "archived": false,
- "archived_info": {
- "time": "2023-08-29T23:15:34Z",
- "user": {
- "email": "john.smith@gmail.com",
- "id": "1234abcd5678"
}
}
}
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",
- "delivery": {
- "state": "delivered",
- "reason": "The email account that you tried to reach does not exist. Please double-check the recipient's email address for typos or unnecessary spaces.",
- "updated_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",
- "delivery": {
- "state": "delivered",
- "reason": "The email account that you tried to reach does not exist. Please double-check the recipient's email address for typos or unnecessary spaces.",
- "updated_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. |
object The medium through which the Adverse Action notification should be sent. |
$ 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' -d 'medium={"email": {"priority": 1, "required": true}, "postal": {"priority": 0, "required": false}}'
{- "id": "e44aa283528e6fde7d542194",
- "object": "adverse_action",
- "uri": "/v1/adverse_actions/57ed51e57619e8002a6683f2",
- "created_at": "2016-09-29T17:39:49Z",
- "delivery": {
- "state": "delivered",
- "reason": "The email account that you tried to reach does not exist. Please double-check the recipient's email address for typos or unnecessary spaces.",
- "updated_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: -d "types[]=driver_license" \ -d "types[]=consent"
{- "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" "citizenship_certificate" "consent" "credit_report_consent_form" "degree" "diploma" "driver_license" "driver_license_back" "driver_license_history" "education_certificate" "education_proof" "electronic_consent_form" "employment_proof" "government_id" "international_consent_form" "military_id" "national_id" "national_id_back" "passport" "passport_signature_page" "paystub" "previous_driver_license" "professional_license_certification_image" "selfie" "ssn_card" "state_id_card" "state_id_card_back" "student_id" "tax_form1099" "tax_form_schedule_c" "tax_form_w2" "taxpayer_id" "transcript" |
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,
- "source": "Self-Disclosure"
}
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,
- "source": "Self-Disclosure"
}
], - "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,
- "source": "Self-Disclosure"
}
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,
- "source": "Self-Disclosure"
}
Deletes 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 DELETE 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,
- "source": "Self-Disclosure"
}
The professional license resource represents a single certification or license issued to a candidate for qualification in a professional field. Candidates may have two existing professional license resources at a time.
Creates a new Professional License for a given candidate. A maximum of two licenses may exist for each candidate. When a report is run with Professional License Verification, all candidate licenses existing at the time of report creation will be included for verification.
candidate_id required | string The Candidate's ID |
expiration_date required | string <date> Expiration date of the professional license |
issuer_name required | string Name of the organization that issued the professional license |
issuer_region required | string 2-letter abbreviation of US state where license was issued. For licenses not issued for a specific state, use "United States". |
license_type required | string Category or industry of professional license |
license_number | string Unique identifier assigned to license by issuer. Format may vary |
certification_document_id required | string ID of document previously created with the uploadDocument endpoint. Document must be of |
$ curl -X POST https://api.checkr.com/v1/candidates/5fb31d36bc2e7f4609aba03d/professional_licenses \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9: \ -d expiration_date=2033-01-30 \ -d issuer_name='Medical Board of California' \ -d issuer_region=CA \ -d license_number=A12345 \ -d license_type=Physician \ -d certification_document_id=4a3e270ccecdd1455d9f4685
{- "id": "e44aa283528e6fde7d542194",
- "expiration_date": "2033-01-30",
- "issuer_name": "Medical Board of California",
- "issuer_region": "CA",
- "license_type": "Physician",
- "license_number": "A 12345"
}
Returns a list of existing Professional Licenses for the given Candidate ID.
candidate_id required | string The Candidate's ID |
$ curl https://api.checkr.com/v1/candidates/5fb31d36bc2e7f4609aba03d/professional_licenses \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
{- "object": "list",
- "count": 1,
- "data": [
- {
- "id": "e44aa283528e6fde7d542194",
- "expiration_date": "2033-01-30",
- "issuer_name": "Medical Board of California",
- "issuer_region": "CA",
- "license_type": "Physician",
- "license_number": "A 12345"
}
]
}
Deletes an existing Professional License
candidate_id required | string The Candidate's ID |
license_id required | string The ID of the license to delete. |
$ curl -X DELETE https://api.checkr.com/v1/candidates/5fb31d36bc2e7f4609aba03d/professional_licenses/de613d6925a27235fc1b64a6 \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9: \
{- "id": "e44aa283528e6fde7d542194",
- "expiration_date": "2033-01-30",
- "issuer_name": "Medical Board of California",
- "issuer_region": "CA",
- "license_type": "Physician",
- "license_number": "A 12345",
- "deleted_at": "2023-10-10T01:16:27.000Z"
}
The School resource includes all relevant educational information for the specified Candidate. School resources are tied to the specified candidate, and do not transfer to other alumna within the system.
Creates a new School resource.
Validation for start_date
and end_date
is performed to ensure logical dates are provided. end_date
must be after start_date
, and both dates must be after 1900-01-01.
If the country is not US, the following parameters are required in addition to those marked as required below:
candidate_id required | string Creates a School for the input |
candidate_id | string non-empty [a-zA-Z0-9 -'.,]* Candidate linked to this School resource. |
name required | string non-empty [a-zA-Z0-9 -'.,]* Name of the School. |
degree required | string Degree awarded to the Candidate. |
year_awarded | integer non-empty Year in which the degree was awarded. |
major required | string[a-zA-Z0-9 -'.,]* Candidate’s major. |
phone | string Nullable School's phone number. |
minor | string Candidate’s minor. |
start_date | string <date> Candidate’s start date with the School. |
end_date | string <date> Candidate’s end date with the School. |
current | boolean Default: false Defines whether the Candidate is currently enrolled. |
school_url | string School’s website. |
required | object (Address) |
$ curl -X POST https://api.checkr.com/v1/candidates/e44aa283528e6fde7d542194/schools \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9: \ -d name=College\ University \ -d address\[street\]=1+Circle+Avenue \ -d address\[city\]=San+Francisco \ -d address\[zipcode\]=94105 \ -d address\[state\]=CA \ -d address\[country\]=US \ -d degree=BS \ -d year_awarded=2017 \ -d major=Computer+Science \ -d phone=111-111-1111 \ -d minor=Background+Checks \ -d start_date=2012-09-25 \ -d end_date=2017-05-29 \ -d current=false \ -d school_url=www.school.com
{- "id": "e44aa283528e6fde7d542194",
- "object": "school",
- "uri": "/v1/schools/e44aa283528e6fde7d542194",
- "candidate_id": "83ebeagdec0948690863766f792ead24d61fe3f9",
- "name": "College University",
- "degree": "BA",
- "year_awarded": 2017,
- "major": "Russian Literature",
- "phone": "415-111-1111",
- "minor": "Background Checks",
- "start_date": "2012-09-22",
- "end_date": "2017-05-10",
- "current": false,
- "school_url": "www.collegeuniversity.com",
- "address": {
- "street": "123 Main St.",
- "unit": 2000,
- "city": "San Francisco",
- "state": "CA",
- "zipcode": "90401",
- "country": "US"
}
}
Returns a list of existing Schools for the input candidate_id
.
candidate_id required | string Returns the list of schools for the input |
$ curl -X GET https://api.checkr.com/v1/candidates/e44aa283528e6fde7d542194/schools/fe8b5a63af2799aba7fdf64d \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
{- "data": [
- {
- "id": "e44aa283528e6fde7d542194",
- "object": "school",
- "uri": "/v1/schools/e44aa283528e6fde7d542194",
- "candidate_id": "83ebeagdec0948690863766f792ead24d61fe3f9",
- "name": "College University",
- "degree": "BA",
- "year_awarded": 2017,
- "major": "Russian Literature",
- "phone": "415-111-1111",
- "minor": "Background Checks",
- "start_date": "2012-09-22",
- "end_date": "2017-05-10",
- "current": false,
- "school_url": "www.collegeuniversity.com",
- "address": {
- "street": "123 Main St.",
- "unit": 2000,
- "city": "San Francisco",
- "state": "CA",
- "zipcode": "90401",
- "country": "US"
}
}
], - "object": "list",
}
Deletes an existing School with the input school_id
.
id required | string The School's ID. |
candidate_id required | string The Candidate's ID. |
$ curl -X DELETE https://api.checkr.com/v1/candidates/e44aa283528e6fde7d542194/schools/95a95172bb81143ed44e403c \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
{- "id": "e44aa283528e6fde7d542194",
- "object": "school",
- "uri": "/v1/schools/e44aa283528e6fde7d542194",
- "candidate_id": "83ebeagdec0948690863766f792ead24d61fe3f9",
- "name": "College University",
- "degree": "BA",
- "year_awarded": 2017,
- "major": "Russian Literature",
- "phone": "415-111-1111",
- "minor": "Background Checks",
- "start_date": "2012-09-22",
- "end_date": "2017-05-10",
- "current": false,
- "school_url": "www.collegeuniversity.com",
- "address": {
- "street": "123 Main St.",
- "unit": 2000,
- "city": "San Francisco",
- "state": "CA",
- "zipcode": "90401",
- "country": "US"
}
}
Returns an existing School with the input school_id
.
id required | string The School's ID. |
candidate_id required | string The Candidate's ID. |
$ curl -X GET https://api.checkr.com/v1/candidates/e44aa283528e6fde7d542194/schools/fe8b5a63af2799aba7fdf64d \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
{- "id": "e44aa283528e6fde7d542194",
- "object": "school",
- "uri": "/v1/schools/e44aa283528e6fde7d542194",
- "candidate_id": "83ebeagdec0948690863766f792ead24d61fe3f9",
- "name": "College University",
- "degree": "BA",
- "year_awarded": 2017,
- "major": "Russian Literature",
- "phone": "415-111-1111",
- "minor": "Background Checks",
- "start_date": "2012-09-22",
- "end_date": "2017-05-10",
- "current": false,
- "school_url": "www.collegeuniversity.com",
- "address": {
- "street": "123 Main St.",
- "unit": 2000,
- "city": "San Francisco",
- "state": "CA",
- "zipcode": "90401",
- "country": "US"
}
}
The Employers resource includes all relevant employer information for the specified Candidate. Employer resources are tied to the specified candidate, and do not transfer to other employees within the system. Once attached to a candidate, all employers are retained when running subsequent employment verifications. For example, if multiple employment verifications are run for an existing candidate, each report will use all employers attached to that candidate for the verification.
Creates a new Employer resource.
If the country is not US, the following parameters will be required in addition to those marked as required in the table below:
Validation for start_date
and end_date
is performed to ensure logical dates are provided. end_date
must be after start_date
, and both dates must be after 1900-01-01.
candidate_id required | string Create an employer for the input |
candidate_id | string non-empty [a-zA-Z0-9 -'.,]* ID of the Candidate being screened. |
type | string Default: "employer" Type of employment history to be created. If type is set to |
name required | string non-empty [a-zA-Z0-9 -'.,]* Candidate’s employer’s name. |
position required | string Candidate’s position or title. |
salary | integer Candidate’s gross salary in dollars annually. |
contract_type required | string Candidate’s contract type. |
do_not_contact | boolean Default: false If |
start_date required | string <date> Candidate’s start date with the employer. |
end_date | string <date> Candidate’s end date with the employer. |
employer_url | string Employer’s website. |
required | object (Address) |
object | |
note | string <= 65535 characters A text note used to add context for an employment gap. |
$ curl -X POST https://api.checkr.com/v1/candidates/e44aa283528e6fde7d542194/employers \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9: \ -d name=Checkr \ -d position=Engineer \ -d salary=10000 \ -d address\[street\]=123+Main+St. \ -d address\[city\]=San+Francisco \ -d address\[state\]=CA \ -d address\[zipcode\]=94108 \ -d address\[country\]=US \ -d contract_type=full_time \ -d start_date=2016-01-22 \ -d end_date=2017-01-22 \ -d manager\[name\]=Joe \ -d manager\[title\]=Manager \ -d employer_url=www.employer.com
{- "id": "e44aa283528e6fde7d542194",
- "object": "employer",
- "uri": "/v1/candidates/e44aa283528e6fde7d542194/employers/ca27df84be5b50dfa7ee1cda",
- "candidate_id": "xxx",
- "name": "Checkr",
- "position": "Software Engineer",
- "salary": 10000,
- "contract_type": "full_time",
- "do_not_contact": false,
- "start_date": "2016-06-01",
- "end_date": "2017-05-01",
- "employer_url": "www.employer.com",
- "address": {
- "street": "123 Main St.",
- "unit": 2000,
- "city": "San Francisco",
- "state": "CA",
- "zipcode": "90401",
- "country": "US"
}, - "manager": {
- "name": "Joe Smith",
- "title": "Engineering Manager",
- "email": "joesmith@checkr.co",
- "phone": "212-555-1234"
}
}
Returns a list of existing Employers for the input candidate_id
.
candidate_id required | string Returns the list of employers for 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/candidates/e44aa283528e6fde7d542194/employers \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
{- "data": [
- {
- "id": "e44aa283528e6fde7d542194",
- "object": "employer",
- "uri": "/v1/candidates/e44aa283528e6fde7d542194/employers/ca27df84be5b50dfa7ee1cda",
- "candidate_id": "xxx",
- "name": "Checkr",
- "position": "Software Engineer",
- "salary": 10000,
- "contract_type": "full_time",
- "do_not_contact": false,
- "start_date": "2016-06-01",
- "end_date": "2017-05-01",
- "employer_url": "www.employer.com",
- "address": {
- "street": "123 Main St.",
- "unit": 2000,
- "city": "San Francisco",
- "state": "CA",
- "zipcode": "90401",
- "country": "US"
}, - "manager": {
- "name": "Joe Smith",
- "title": "Engineering Manager",
- "email": "joesmith@checkr.co",
- "phone": "212-555-1234"
}
}
], - "object": "list",
- "count": 2
}
Deletes an existing Employer with the input id
.
employer_id required | string The Employer's ID. |
candidate_id required | string The Candidate's ID. |
$ curl -X DELETE https://api.checkr.com/v1/candidates/e44aa283528e6fde7d542194/employers/95a95172bb81143ed44e403c \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
{- "id": "e44aa283528e6fde7d542194",
- "object": "employer",
- "uri": "/v1/candidates/e44aa283528e6fde7d542194/employers/ca27df84be5b50dfa7ee1cda",
- "candidate_id": "xxx",
- "name": "Checkr",
- "position": "Software Engineer",
- "salary": 10000,
- "contract_type": "full_time",
- "do_not_contact": false,
- "start_date": "2016-06-01",
- "end_date": "2017-05-01",
- "employer_url": "www.employer.com",
- "address": {
- "street": "123 Main St.",
- "unit": 2000,
- "city": "San Francisco",
- "state": "CA",
- "zipcode": "90401",
- "country": "US"
}, - "manager": {
- "name": "Joe Smith",
- "title": "Engineering Manager",
- "email": "joesmith@checkr.co",
- "phone": "212-555-1234"
}
}
Returns an existing Employer with the input candidate_id
or employer_id
.
employer_id required | string The Employer's ID. |
candidate_id required | string The Candidate's ID. |
$ curl -X GET https://api.checkr.com/v1/candidates/e44aa283528e6fde7d542194/employers/ca27df84be5b50dfa7ee1cda \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
{- "id": "e44aa283528e6fde7d542194",
- "object": "employer",
- "uri": "/v1/candidates/e44aa283528e6fde7d542194/employers/ca27df84be5b50dfa7ee1cda",
- "candidate_id": "xxx",
- "name": "Checkr",
- "position": "Software Engineer",
- "salary": 10000,
- "contract_type": "full_time",
- "do_not_contact": false,
- "start_date": "2016-06-01",
- "end_date": "2017-05-01",
- "employer_url": "www.employer.com",
- "address": {
- "street": "123 Main St.",
- "unit": 2000,
- "city": "San Francisco",
- "state": "CA",
- "zipcode": "90401",
- "country": "US"
}, - "manager": {
- "name": "Joe Smith",
- "title": "Engineering Manager",
- "email": "joesmith@checkr.co",
- "phone": "212-555-1234"
}
}
The Counties resource provides a list of all counties within the United States. Use the returned list to validate the counties submitted by your candidates during the Self Disclosure process.
Returns a list of all counties for the input state(s). If no state is provided with the query, returns a list of all counties in the United States.
states | string A comma-separated list of states' Federal Information Processing Series (FIPS) values to query. |
$ curl -X GET https://api.checkr.com/v1/counties?states=HI \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
{- "HI": {
- "counties": [
- {
- "name": "HAWAII",
- "fips_code": "15001"
}, - {
- "name": "HONOLULU",
- "fips_code": "15003"
}, - {
- "name": "KALAWAO",
- "fips_code": "15005"
}, - {
- "name": "KAUAI",
- "fips_code": "15007"
}, - {
- "name": "MAUI",
- "fips_code": "15009"
}
]
}
}
This request is used to add a tag to a Report.
Note: The tag
value passed to POST /v1/reports/{id}/tags
will match the name
field in the response.
id required | string The Report's ID. |
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. |
tag required | string |
curl -X POST https://api.checkr.com/v1/reports/4722c07dd9a10c3985ae432a/tags \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9: \ -d tag=In+Progress
{- "count": 3,
- "object": "list",
- "data": [
- {
- "name": "EIN-234234234"
}, - {
- "name": "api-generated"
}, - {
- "name": "In Progress"
}
]
}
This request is used to define all tags for a Report.
id required | string The Report's ID. |
tags required | Array of strings |
curl -X PUT https://api.checkr.com/v1/reports/4722c07dd9a10c3985ae432a/tags \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9: \ -d tags[]=West+Coast \ -d tags[]=To+Review
{- "count": 2,
- "object": "list",
- "data": [
- {
- "name": "West Coast"
}, - {
- "name": "To Review"
}
]
}
Retrieves tags for the input Report.
id required | string The Report's ID. |
curl -X GET https://api.checkr.com/v1/reports/4722c07dd9a10c3985ae432a/tags \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
{- "count": 2,
- "object": "list",
- "data": [
- {
- "name": "EIN-234234234"
}, - {
- "name": "api-generated"
}
]
}
This request is used to delete a tag from a Report.
id required | string The Report's ID. |
tag required | string |
curl -X DELETE https://api.checkr.com/v1/reports/4722c07dd9a10c3985ae432a/tags \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9: \ -d tag=West+Coast
{- "count": 1,
- "object": "list",
- "data": [
- {
- "name": "To Review"
}
]
}
This request is used to retrieve addresses for a given Report.
report_id required | string Returns the list of Report addresses for 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/reports/4722c07dd9a10c3985ae432a/addresses \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
{- "data": [
- {
- "name": "UCSF",
- "city": "San Francisco",
- "state": "CA",
- "start_date": "2018-07-22T17:41:20Z",
- "end_date": "2018-01-24T17:41:20Z"
}
], - "object": "list",
- "count": 1
}
Report ETAs predict when screenings will complete for each background check report. This ETA provides a date for the estimated completion of a specific report, helping both you and your candidates plan ahead.
While the predictions are highly accurate, they are not a guarantee. Some county-level searches are subject to unpredictable timelines, due to manual search processes and court availability. For more information on these searches, please see County Criminal Record Search in the Checkr Help Center.
90% of reports will complete within one business day of the estimated date.
For those reports which do not complete within the initial estimate, Checkr will re-generate the ETA using the current information available for the remaining screenings. A report.updated webhook will be issued for both the initial and each subsequent ETA.
For more information, see Checkr ETA in the Checkr Help Center.
Returns an existing Report ETA for the input Report ID.
id required | string ID of the Report for which the ETA was generated. |
curl -X GET https://api.checkr.com/v1/reports/4722c07dd9a10c3985ae432a/eta \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
{- "estimate_generated_at": "2014-01-18T12:34:00Z",
- "estimated_completion_time": "2019-07-31T00:00:00Z"
}
Candidate Stories allows candidates with records the opportunity to share additional context about themselves and their background checks. Once submitted, these stories will be available to customers in the candidate’s report in the Checkr Dashboard.
For more information, please see Candidate Stories: Improving understanding of the past and present in the Checkr Help Center.
Returns the existing Candidate Story corresponding to the input ID.
id required | string ID of the Candidate Story. |
{- "id": "e44aa283528e6fde7d542194",
- "object": "candidate_story",
- "uri": "/v1/candidate_stories/e44aa283528e6fde7d542194",
- "report_id": "af3393b7d751206c7c67b6e5",
- "record": {
- "id": "4e2a551f79e0095b35d4d3ca",
- "case_number": "NMND78D",
- "charge": "LIGHT OFFENSE",
- "offense_date": "2020-01-20",
- "location": "San Mateo, CA"
}, - "content": "Since my case, I have received the following certifications (see attachments)",
- "created_at": "2020-04-17T07:48:34Z",
- "documents": [
- {
- "id": "e44aa283528e6fde7d542194",
- "object": "document",
- "type": "candidate_story_document",
- "created_at": "2020-04-17T07:48:01Z",
- "filesize": 8576,
- "filename": "proof_of_rehabilitation.pdf",
- "content_type": "image/pdf"
}
]
}
Deletes the existing Candidate Story corresponding to the input ID.
id required | string ID of the Candidate Story. |
{- "id": "e44aa283528e6fde7d542194",
- "object": "candidate_story",
- "uri": "/v1/candidate_stories/e44aa283528e6fde7d542194",
- "report_id": "af3393b7d751206c7c67b6e5",
- "record": {
- "id": "4e2a551f79e0095b35d4d3ca",
- "case_number": "NMND78D",
- "charge": "LIGHT OFFENSE",
- "offense_date": "2020-01-20",
- "location": "San Mateo, CA"
}, - "content": "Since my case, I have received the following certifications (see attachments)",
- "created_at": "2020-04-17T07:48:34Z",
- "documents": [
- {
- "id": "e44aa283528e6fde7d542194",
- "object": "document",
- "type": "candidate_story_document",
- "created_at": "2020-04-17T07:48:01Z",
- "filesize": 8576,
- "filename": "proof_of_rehabilitation.pdf",
- "content_type": "image/pdf"
}
]
}
Create a new Candidate Story for the input report_id
.
report_id required | string Create an candidate story for the input |
content required | string Additional information provided by Candidate. |
record_id | string ID of the Record existing on a Screening to which the Candidate Story is linked. When no record ID is provided, the Candidate Story is considered General Information. |
required | Array of objects An array of documents to attach to the Candidate Story. Can be empty. |
{- "content": "Since my case, I have received the following certifications (see attachments)",
- "record_id": "af3393b7d751206c7c67b6e5",
- "documents": [
- {
- "filename": "evidence_of_rehab.pdf",
- "type": "application/pdf"
}
]
}
{- "id": "e44aa283528e6fde7d542194",
- "object": "candidate_story",
- "uri": "/v1/candidate_stories/e44aa283528e6fde7d542194",
- "report_id": "af3393b7d751206c7c67b6e5",
- "record": {
- "id": "4e2a551f79e0095b35d4d3ca",
- "case_number": "NMND78D",
- "charge": "LIGHT OFFENSE",
- "offense_date": "2020-01-20",
- "location": "San Mateo, CA"
}, - "content": "Since my case, I have received the following certifications (see attachments)",
- "created_at": "2020-04-17T07:48:34Z",
- "documents": [
- {
- "id": "e44aa283528e6fde7d542194",
- "object": "document",
- "type": "candidate_story_document",
- "created_at": "2020-04-17T07:48:01Z",
- "filesize": 8576,
- "filename": "proof_of_rehabilitation.pdf",
- "content_type": "image/pdf"
}
]
}
The SSN resource allows you to retrieve a candidate's encrypted SSN.
Note: Access to this endpoint requires an RSA key-pair for encryption. See Configuring Encryption for Candidate SSN Endpoint for information on how to generate encryption keys. Work with your Checkr Customer Success Manager to enable this feature for your account.
Returns an encrypted SSN for the input candidate_id
.
candidate_id required | string The candidate's ID. |
$ curl -X GET https://api.checkr.com/v1/candidates/e44aa283528e6fde7d542194/ssn/ \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
{- "encrypted_ssn": "hyYMhDje9dVUEPKU9myy7OFJ7R27pj0pmlegFlka99I="
}
Use webhooks to receive updates on objects created with the API and to kick off additional workflows based on these events. See Webhooks for more information.
Creates a new Webhook resource. An account can have a maximum of 2 webhooks.
Any webhook URL that fails to accept with a 2XX status code at least one request over a period of 60 days will be removed automatically - e.g. webhooks failing for 100% of the requests during 60 or more days.
include_object | boolean When |
webhook_url required | string The URL which receives the webhook event payload. This must be an HTTPS or an AWS SNS URL. For more information, see Supported Webhook URLs section. |
live | boolean When 'true', the webhook is for the live environment. |
$ curl -X POST https://api.checkr.com/v1/webhooks \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9: \ -d include_object=true \ -d webhook_url=https://example.com
{- "id": "e44aa283528e6fde7d542194",
- "object": "webhook",
- "uri": "/v1/webhooks/e44aa283528e6fde7d542194",
- "account_id": "8e122cc56b8fa82d33c6118a",
- "application_id": null,
- "include_object": true,
- "created_at": "1939-09-01T12:21:00Z",
- "deleted_at": null
}
$ curl -X GET https://api.checkr.com/v1/webhooks \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
{- "object": "list",
- "count": 2,
- "data": [
- {
- "id": "e44aa283528e6fde7d542194",
- "object": "webhook",
- "uri": "/v1/webhooks/e44aa283528e6fde7d542194",
- "account_id": "8e122cc56b8fa82d33c6118a",
- "application_id": null,
- "include_object": true,
- "created_at": "1939-09-01T12:21:00Z",
- "deleted_at": null
}
]
}
Returns the existing Webhook corresponding to the input ID.
id required | string ID of the Webhook. |
$ curl -X GET https://api.checkr.com/v1/webhooks/e44aa283528e6fde7d542194 \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
{- "id": "e44aa283528e6fde7d542194",
- "object": "webhook",
- "uri": "/v1/webhooks/e44aa283528e6fde7d542194",
- "account_id": "8e122cc56b8fa82d33c6118a",
- "application_id": null,
- "include_object": true,
- "created_at": "1939-09-01T12:21:00Z",
- "deleted_at": null
}
Deletes the existing Webhook corresponding to the input ID.
id required | string ID of the Webhook. |
curl -X DELETE https://api.checkrhq-staging.net/v1/webhooks/e44aa283528e6fde7d542194 \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
{- "id": "e44aa283528e6fde7d542194",
- "object": "webhook",
- "uri": "/v1/webhooks/e44aa283528e6fde7d542194",
- "account_id": "8e122cc56b8fa82d33c6118a",
- "application_id": null,
- "include_object": true,
- "created_at": "1939-09-01T12:21:00Z",
- "deleted_at": "1945-09-02T04:40:00Z"
}
The candidate postal address is the address Checkr will use to send postal mail to the candidate. Each candidate can be associated with only one postal address.
Returns the Postal Address of a given candidate.
candidate_id required | string The candidate's ID. |
curl -X GET https://api.checkr.com/v1/candidates/e44aa283528e6fde7d542194/postal_address \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
{- "id": "e44aa283528e6fde7d542194",
- "object": "candidate_postal_address",
- "candidate_id": "e44aa283528e6fde7d542194",
- "uri": "/v1/candidate/e44aa283528e6fde7d542194/postal_address",
- "name": "John Alfred Smith",
- "street": "123 Main St",
- "street2": "Apt A",
- "city": "Santa Monica",
- "state": "CA",
- "zipcode": "90401"
}
Creates a new Postal Address for a given candidate.
candidate_id required | string The candidate's ID. |
name required | string Name of the Candidate. |
street required | string Street address of the Candidate. |
street2 | string Nullable Additional street address of the Candidate. |
city required | string City of the Candidate. |
state required | string State of the Candidate. |
zipcode required | string 5-digit zip code of the Candidate. |
curl -X POST https://api.checkr.com/v1/candidates/e44aa283528e6fde7d542194/postal_address \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9: \ -d '{ "name": "John Alfred Smith", "street": "123 Main Street", "street2": "APT A", "city": "San Francisco", "state": "CA", "zipcode": "94108" }'
{- "id": "e44aa283528e6fde7d542194",
- "object": "candidate_postal_address",
- "candidate_id": "e44aa283528e6fde7d542194",
- "uri": "/v1/candidate/e44aa283528e6fde7d542194/postal_address",
- "name": "John Alfred Smith",
- "street": "123 Main St",
- "street2": "Apt A",
- "city": "Santa Monica",
- "state": "CA",
- "zipcode": "90401"
}
SSN Trace is typically the first screening run, and is used to verify that the input SSN exists, determine where and when it was issued, and to compile a list of all known aliases associated with the SSN. This Trace is also used to generate a list of all known addresses recorded by credit agencies for the SSN for the last 7 years.
An SSN Trace may be used to determine which additional jurisdictions should be searched for the candidate, based on the list of known addresses returned.
If the platform detects an issue with the SSN Trace run (data mismatch, absence of data, or inclusion of the SSN on the death master file), Checkr may issue an exception and ask the candidate to either re-enter their SSN or upload other supporting documentation.
Note: Information returned by this search is not a part of the consumer report and may not be used for FCRA purposes, including eligibility determinations under the FCRA
For more information, please see SSN Trace in the Checkr Help Center.
Returns an existing SSN Trace with the input ID.
id required | string ID of the SSN Trace to retrieve. |
$ curl -X GET https://api.checkr.com/v1/ssn_traces/539fd88c101897f7cd000001 \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
{- "id": "e44aa283528e6fde7d542194",
- "object": "ssn_trace",
- "uri": "/v1/ssn_traces/539fd88c101897f7cd000001",
- "status": "complete",
- "result": null,
- "created_at": "2014-01-18T12:34:00Z",
- "completed_at": "2014-01-18T12:35:30Z",
- "turnaround_time": 90,
- "cancellation_reason": null,
- "cancellation_reason_description": null,
- "ssn": "XXX-XX-4645",
- "no_data": false,
- "dob_mismatch": false,
- "name_mismatch": false,
- "data_mismatch": false,
- "thin_file": false,
- "invalid_issuance_year": false,
- "death_index": false,
- "ssn_already_taken": false,
- "issued_year": 1993,
- "issued_state": "CA",
- "addresses": [ ],
- "aliases": [ ]
}
Represents an instant multi-state Sex Offender Registry Search.
A nationwide search of all 50 states' and the District of Columbia’s sex offender registries for all levels of registered sex offenders. Search includes type(s) of offense and identifiers, such as Date of Birth (DOB).
For more information, please see Sex Offender Registry Search in the Checkr Help Center.
Returns an existing Sex Offender Registry Search with the input ID.
id required | string ID of the Sex Offender Search to retrieve. |
$ curl -X GET https://api.checkr.com/v1/sex_offender_searches/539fd88c101897f7cd000008 \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
{- "id": "e44aa283528e6fde7d542194",
- "object": "sex_offender_search",
- "uri": "/v1/sex_offender_searches/539fd88c101897f7cd000008",
- "status": "complete",
- "result": "consider",
- "assessment": "eligible",
- "created_at": "2014-01-18T12:34:00Z",
- "completed_at": "2014-01-18T12:35:30Z",
- "turnaround_time": 90,
- "cancellation_reason": "complete_now_customer_requested",
- "cancellation_reason_description": "Customer requested Complete Now prior to screening completion",
- "records": [
- {
- "registry": "California",
- "full_name": "John Alfred Smith",
- "age": 44,
- "dob": "1975-02-01",
- "registration_start": "2011-02-12",
- "registration_end": "2012-02-12",
- "state": "CA"
}
]
}
The Global Watchlist Search searches known domestic and international terrorist watchlists as well as the records of the Office of Inspector General (OIG), Excluded Parties List (EPL) and additional domestic and international agency lists.
For more information, please see Global Watchlist Search in the Checkr Help Center.
Returns an existing Global Watchlist Search with the input ID.
id required | string ID of the Global Watchlist Search to retrieve. |
$ curl -X GET https://api.checkr.com/v1/global_watchlist_searches/539fd88c101897f7cd000008 \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
{- "id": "e44aa283528e6fde7d542194",
- "object": "global_watchlist_search",
- "uri": "/v1/global_watchlist_searches/539fd88c101897f7cd000008",
- "status": "complete",
- "result": "consider",
- "assessment": "eligible",
- "created_at": "2014-01-18T12:34:00Z",
- "completed_at": "2014-01-18T12:35:30Z",
- "turnaround_time": 90,
- "cancellation_reason": "complete_now_customer_requested",
- "cancellation_reason_description": "Customer requested Complete Now prior to screening completion",
- "records": [
- {
- "id": "e44aa283528e6fde7d542194",
- "case_number": "24323-DA",
- "file_date": null,
- "arresting_agency": "DEA Boston Division",
- "court_jurisdiction": null,
- "court_of_record": null,
- "full_name": "John Alfred Smith",
- "dob": "1970-01-22",
- "yob": 1970,
- "county": "SUFFOLK",
- "state": "MA",
- "address": {
- "street": "123 Main St.",
- "unit": 2000,
- "city": "San Francisco",
- "state": "CA",
- "zipcode": "90401",
- "country": "US"
}, - "charges": [
- {
- "id": "e44aa283528e6fde7d542194",
- "charge": "RICO murder",
- "category": "fraud_and_deception",
- "charge_type": null,
- "charge_id": null,
- "classification": "Felony",
- "deposition": null,
- "defendant": null,
- "plaintiff": null,
- "sentence": "Active Punishment Minimum: 10Y",
- "disposition": "Guilty",
- "probation_status": null,
- "offense_date": "2011-04-22",
- "deposition_date": "2014-05-27",
- "arrest_date": null,
- "charge_date": null,
- "sentence_date": null,
- "disposition_date": "2011-06-02",
- "conviction_date": "2011-06-02",
- "release_date": "2011-06-02",
- "next_court_date": "2011-06-02",
- "court": "Circuit & District Court",
- "plea": null,
- "assessment": null,
- "prison_time": "4 Year(s)",
- "jail_time": "15 Day(s)",
- "probation_time": null,
- "restitution": "220.00"
}
]
}
]
}
Checkr conducts a National Criminal Database Search as a routine part of all criminal background checks. The search queries 3,200 counties and over 900 million records across the United States, and provides a quick means to evaluate which courts or jurisdictions should be searched more thoroughly for any given candidate.
The National Criminal Database Search is used only as a "pointer search" to determine which courts or jurisdictions to search. Records returned from this database do not appear on the final report.
For more information, please see National Criminal Database Search in the Checkr Help Center.
Returns an existing National Criminal Search with the input ID.
id required | string ID of the National Criminal Search to retrieve. |
$ curl -X GET https://api.checkr.com/v1/national_criminal_searches/539fd88c101897f7cd000006 \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
{- "id": "e44aa283528e6fde7d542194",
- "object": "national_criminal_search",
- "uri": "/v1/national_criminal_searches/539fd88c101897f7cd000006",
- "status": "complete",
- "result": null,
- "created_at": "2014-01-18T12:34:00Z",
- "completed_at": "2014-01-18T12:35:30Z",
- "turnaround_time": 90,
- "cancellation_reason": null,
- "cancellation_reason_description": null,
- "records": [
- {
- "id": "e44aa283528e6fde7d542194",
- "case_number": "24323-DA",
- "file_date": null,
- "arresting_agency": null,
- "court_jurisdiction": null,
- "court_of_record": null,
- "full_name": "John Alfred Smith",
- "dob": "1970-01-22",
- "yob": 1970,
- "county": "SUFFOLK",
- "state": "MA",
- "address": {
- "street": "123 Main St.",
- "unit": 2000,
- "city": "San Francisco",
- "state": "CA",
- "zipcode": "90401",
- "country": "US"
}, - "charges": [
- {
- "id": "e44aa283528e6fde7d542194",
- "charge": "Fraud",
- "category": "fraud_and_deception",
- "charge_type": null,
- "charge_id": null,
- "classification": "Felony",
- "deposition": null,
- "defendant": null,
- "plaintiff": null,
- "sentence": "Active Punishment Minimum: 10Y",
- "disposition": "Guilty",
- "probation_status": null,
- "offense_date": "2011-04-22",
- "deposition_date": "2014-05-27",
- "arrest_date": null,
- "charge_date": null,
- "sentence_date": null,
- "disposition_date": "2011-06-02",
- "conviction_date": "2011-06-02",
- "release_date": "2011-06-02",
- "next_court_date": "2011-06-02",
- "court": "Circuit & District Court",
- "plea": null,
- "assessment": null,
- "prison_time": "4 Year(s)",
- "jail_time": "15 Day(s)",
- "probation_time": null,
- "restitution": "220.00"
}
]
}
]
}
Searches the Federal Criminal record database and Federal District courts to return felony and misdemeanor records. (National, State, and County Criminal Searches do not return federal records.) For more information, please see Federal Criminal Search in the Checkr Help Center.
Returns an existing Federal Criminal Search with the input ID.
id required | string ID of the Federal Criminal Search to retrieve. |
exclude | string Indicates whether to return disctrict screenings in pointer search payload Example: exclude=district |
$ curl -X GET https://api.checkr.com/v1/federal_criminal_searches/539fd88c101897f7cd000006 \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
{- "id": "e44aa283528e6fde7d542194",
- "object": "federal_criminal_search",
- "uri": "/v1/federal_criminal_searches/539fd88c101897f7cd000006",
- "status": "complete",
- "result": "clear",
- "created_at": "2014-01-18T12:34:00Z",
- "completed_at": "2014-01-18T12:35:30Z",
- "turnaround_time": 90,
- "cancellation_reason": null,
- "cancellation_reason_description": null,
- "assessment": "eligible",
- "records": [
- {
- "id": "e44aa283528e6fde7d542194",
- "case_number": "24323-DA",
- "file_date": null,
- "arresting_agency": null,
- "court_jurisdiction": null,
- "court_of_record": null,
- "full_name": "John Alfred Smith",
- "dob": "1970-01-22",
- "yob": 1970,
- "county": "SUFFOLK",
- "state": "MA",
- "address": {
- "street": "123 Main St.",
- "unit": 2000,
- "city": "San Francisco",
- "state": "CA",
- "zipcode": "90401",
- "country": "US"
}, - "charges": [
- {
- "id": "e44aa283528e6fde7d542194",
- "charge": "Fraud",
- "category": "fraud_and_deception",
- "charge_type": null,
- "charge_id": null,
- "classification": "Felony",
- "deposition": null,
- "defendant": null,
- "plaintiff": null,
- "sentence": "Active Punishment Minimum: 10Y",
- "disposition": "Guilty",
- "probation_status": null,
- "offense_date": "2011-04-22",
- "deposition_date": "2014-05-27",
- "arrest_date": null,
- "charge_date": null,
- "sentence_date": null,
- "disposition_date": "2011-06-02",
- "conviction_date": "2011-06-02",
- "release_date": "2011-06-02",
- "next_court_date": "2011-06-02",
- "court": "Circuit & District Court",
- "plea": null,
- "assessment": null,
- "prison_time": "4 Year(s)",
- "jail_time": "15 Day(s)",
- "probation_time": null,
- "restitution": "220.00"
}
]
}
], - "filtered_by_positive_adjudication_records": [
- {
- "id": "e44aa283528e6fde7d542194",
- "case_number": "24323-DA",
- "file_date": null,
- "arresting_agency": "DEA Boston Division",
- "court_jurisdiction": null,
- "court_of_record": null,
- "full_name": "John Alfred Smith",
- "dob": "1970-01-22",
- "yob": 1970,
- "county": "SUFFOLK",
- "state": "MA",
- "address": {
- "street": "123 Main St.",
- "unit": 2000,
- "city": "San Francisco",
- "state": "CA",
- "zipcode": "90401",
- "country": "US"
}, - "filtered_by_positive_adjudication_charges": [
- {
- "id": "e44aa283528e6fde7d542194",
- "charge": "Fraud",
- "category": "fraud_and_deception",
- "charge_type": null,
- "charge_id": null,
- "classification": "Felony",
- "deposition": null,
- "defendant": null,
- "plaintiff": null,
- "sentence": "Active Punishment Minimum: 10Y",
- "disposition": "Guilty",
- "probation_status": null,
- "offense_date": "2011-04-22",
- "deposition_date": "2014-05-27",
- "arrest_date": null,
- "charge_date": null,
- "sentence_date": null,
- "disposition_date": "2011-06-02",
- "conviction_date": "2011-06-02",
- "release_date": "2011-06-02",
- "next_court_date": "2011-06-02",
- "court": "Circuit & District Court",
- "plea": null,
- "assessment": null,
- "prison_time": "4 Year(s)",
- "jail_time": "15 Day(s)",
- "probation_time": null,
- "restitution": "220.00"
}
]
}
]
}
Searches Federal District Criminal courts to verify felony and misdemeanor records identified by PACER. For more information, please see Federal District Criminal Search in the Checkr Help Center.
Returns an existing Federal District Criminal Search with the input ID.
id required | string ID of the Federal District Criminal Search to retrieve. |
$ curl -X GET https://api.checkr.com/v1/federal_district_criminal_searches/539fd88c101897f7cd000006 \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
{- "id": "e44aa283528e6fde7d542194",
- "object": "federal_district_criminal_search",
- "uri": "/v1/federal_district_criminal_searches/625487abdc27f729a9997f50",
- "status": "complete",
- "result": "clear",
- "assessment": "eligible",
- "created_at": "2014-01-18T12:34:00Z",
- "completed_at": "2014-01-18T12:35:30Z",
- "turnaround_time": 90,
- "cancellation_reason": "complete_now_customer_requested",
- "cancellation_reason_description": "Customer requested Complete Now prior to screening completion",
- "records": [
- {
- "id": "e44aa283528e6fde7d542194",
- "case_number": "24323-DA",
- "file_date": null,
- "arresting_agency": null,
- "court_jurisdiction": null,
- "court_of_record": null,
- "full_name": "John Alfred Smith",
- "dob": "1970-01-22",
- "yob": 1970,
- "county": "SUFFOLK",
- "state": "MA",
- "address": {
- "street": "123 Main St.",
- "unit": 2000,
- "city": "San Francisco",
- "state": "CA",
- "zipcode": "90401",
- "country": "US"
}, - "charges": [
- {
- "id": "e44aa283528e6fde7d542194",
- "charge": "Fraud",
- "category": "fraud_and_deception",
- "charge_type": null,
- "charge_id": null,
- "classification": "Felony",
- "deposition": null,
- "defendant": null,
- "plaintiff": null,
- "sentence": "Active Punishment Minimum: 10Y",
- "disposition": "Guilty",
- "probation_status": null,
- "offense_date": "2011-04-22",
- "deposition_date": "2014-05-27",
- "arrest_date": null,
- "charge_date": null,
- "sentence_date": null,
- "disposition_date": "2011-06-02",
- "conviction_date": "2011-06-02",
- "release_date": "2011-06-02",
- "next_court_date": "2011-06-02",
- "court": "Circuit & District Court",
- "plea": null,
- "assessment": null,
- "prison_time": "4 Year(s)",
- "jail_time": "15 Day(s)",
- "probation_time": null,
- "restitution": "220.00"
}
]
}
], - "records_hidden_by_assess": [
- {
- "id": "e44aa283528e6fde7d542194",
- "case_number": "24323-DA",
- "file_date": null,
- "arresting_agency": "DEA Boston Division",
- "court_jurisdiction": null,
- "court_of_record": null,
- "full_name": "John Alfred Smith",
- "dob": "1970-01-22",
- "yob": 1970,
- "county": "SUFFOLK",
- "state": "MA",
- "address": {
- "street": "123 Main St.",
- "unit": 2000,
- "city": "San Francisco",
- "state": "CA",
- "zipcode": "90401",
- "country": "US"
}, - "charges_hidden_by_assess": [
- {
- "id": "e44aa283528e6fde7d542194",
- "charge": "Fraud",
- "category": "fraud_and_deception",
- "charge_type": null,
- "charge_id": null,
- "classification": "Felony",
- "deposition": null,
- "defendant": null,
- "plaintiff": null,
- "sentence": "Active Punishment Minimum: 10Y",
- "disposition": "Guilty",
- "probation_status": null,
- "offense_date": "2011-04-22",
- "deposition_date": "2014-05-27",
- "arrest_date": null,
- "charge_date": null,
- "sentence_date": null,
- "disposition_date": "2011-06-02",
- "conviction_date": "2011-06-02",
- "release_date": "2011-06-02",
- "next_court_date": "2011-06-02",
- "court": "Circuit & District Court",
- "plea": null,
- "assessment": null,
- "prison_time": "4 Year(s)",
- "jail_time": "15 Day(s)",
- "probation_time": null,
- "restitution": "220.00"
}
]
}
], - "filtered_by_positive_adjudication_records": [
- {
- "id": "e44aa283528e6fde7d542194",
- "case_number": "24323-DA",
- "file_date": null,
- "arresting_agency": "DEA Boston Division",
- "court_jurisdiction": null,
- "court_of_record": null,
- "full_name": "John Alfred Smith",
- "dob": "1970-01-22",
- "yob": 1970,
- "county": "SUFFOLK",
- "state": "MA",
- "address": {
- "street": "123 Main St.",
- "unit": 2000,
- "city": "San Francisco",
- "state": "CA",
- "zipcode": "90401",
- "country": "US"
}, - "filtered_by_positive_adjudication_charges": [
- {
- "id": "e44aa283528e6fde7d542194",
- "charge": "Fraud",
- "category": "fraud_and_deception",
- "charge_type": null,
- "charge_id": null,
- "classification": "Felony",
- "deposition": null,
- "defendant": null,
- "plaintiff": null,
- "sentence": "Active Punishment Minimum: 10Y",
- "disposition": "Guilty",
- "probation_status": null,
- "offense_date": "2011-04-22",
- "deposition_date": "2014-05-27",
- "arrest_date": null,
- "charge_date": null,
- "sentence_date": null,
- "disposition_date": "2011-06-02",
- "conviction_date": "2011-06-02",
- "release_date": "2011-06-02",
- "next_court_date": "2011-06-02",
- "court": "Circuit & District Court",
- "plea": null,
- "assessment": null,
- "prison_time": "4 Year(s)",
- "jail_time": "15 Day(s)",
- "probation_time": null,
- "restitution": "220.00"
}
]
}
]
}
Searches the PACER database to identify Federal Civil records. Checkr conducts Federal District Searches to verify records identified by this search. For more information, please see Federal Civil District Search in the Checkr Help Center.
Returns an existing Federal Civil Search with the input ID.
id required | string ID of the Federal Civil Search to retrieve. |
exclude | string Indicates whether to return district screenings in pointer search payload Example: exclude=district |
$ curl -X GET https://api.checkr.com/v1/federal_civil_searches/539fd88c101897f7cd000006 \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
{- "id": "e44aa283528e6fde7d542194",
- "object": "federal_civil_search",
- "uri": "/v1/federal_civil_searches/625487abdc27f729a9997f50",
- "status": "complete",
- "result": "clear",
- "created_at": "2014-01-18T12:34:00Z",
- "completed_at": "2014-01-18T12:35:30Z",
- "turnaround_time": 90,
- "cancellation_reason": null,
- "cancellation_reason_description": null,
- "records": [
- {
- "id": "e44aa283528e6fde7d542194",
- "case_number": "24323-DA",
- "file_date": null,
- "arresting_agency": null,
- "court_jurisdiction": null,
- "court_of_record": null,
- "full_name": "John Alfred Smith",
- "dob": "1970-01-22",
- "yob": 1970,
- "county": "SUFFOLK",
- "state": "MA",
- "address": {
- "street": "123 Main St.",
- "unit": 2000,
- "city": "San Francisco",
- "state": "CA",
- "zipcode": "90401",
- "country": "US"
}, - "charges": [
- {
- "id": "e44aa283528e6fde7d542194",
- "charge": "Fraud",
- "category": "fraud_and_deception",
- "charge_type": null,
- "charge_id": null,
- "classification": "Felony",
- "deposition": null,
- "defendant": null,
- "plaintiff": null,
- "sentence": "Active Punishment Minimum: 10Y",
- "disposition": "Guilty",
- "probation_status": null,
- "offense_date": "2011-04-22",
- "deposition_date": "2014-05-27",
- "arrest_date": null,
- "charge_date": null,
- "sentence_date": null,
- "disposition_date": "2011-06-02",
- "conviction_date": "2011-06-02",
- "release_date": "2011-06-02",
- "next_court_date": "2011-06-02",
- "court": "Circuit & District Court",
- "plea": null,
- "assessment": null,
- "prison_time": "4 Year(s)",
- "jail_time": "15 Day(s)",
- "probation_time": null,
- "restitution": "220.00"
}
]
}
], - "records_hidden_by_assess": [
- {
- "id": "e44aa283528e6fde7d542194",
- "case_number": "24323-DA",
- "file_date": null,
- "arresting_agency": "DEA Boston Division",
- "court_jurisdiction": null,
- "court_of_record": null,
- "full_name": "John Alfred Smith",
- "dob": "1970-01-22",
- "yob": 1970,
- "county": "SUFFOLK",
- "state": "MA",
- "address": {
- "street": "123 Main St.",
- "unit": 2000,
- "city": "San Francisco",
- "state": "CA",
- "zipcode": "90401",
- "country": "US"
}, - "charges_hidden_by_assess": [
- {
- "id": "e44aa283528e6fde7d542194",
- "charge": "Fraud",
- "category": "fraud_and_deception",
- "charge_type": null,
- "charge_id": null,
- "classification": "Felony",
- "deposition": null,
- "defendant": null,
- "plaintiff": null,
- "sentence": "Active Punishment Minimum: 10Y",
- "disposition": "Guilty",
- "probation_status": null,
- "offense_date": "2011-04-22",
- "deposition_date": "2014-05-27",
- "arrest_date": null,
- "charge_date": null,
- "sentence_date": null,
- "disposition_date": "2011-06-02",
- "conviction_date": "2011-06-02",
- "release_date": "2011-06-02",
- "next_court_date": "2011-06-02",
- "court": "Circuit & District Court",
- "plea": null,
- "assessment": null,
- "prison_time": "4 Year(s)",
- "jail_time": "15 Day(s)",
- "probation_time": null,
- "restitution": "220.00"
}
]
}
], - "filtered_by_positive_adjudication_records": [
- {
- "id": "e44aa283528e6fde7d542194",
- "case_number": "24323-DA",
- "file_date": null,
- "arresting_agency": "DEA Boston Division",
- "court_jurisdiction": null,
- "court_of_record": null,
- "full_name": "John Alfred Smith",
- "dob": "1970-01-22",
- "yob": 1970,
- "county": "SUFFOLK",
- "state": "MA",
- "address": {
- "street": "123 Main St.",
- "unit": 2000,
- "city": "San Francisco",
- "state": "CA",
- "zipcode": "90401",
- "country": "US"
}, - "filtered_by_positive_adjudication_charges": [
- {
- "id": "e44aa283528e6fde7d542194",
- "charge": "Fraud",
- "category": "fraud_and_deception",
- "charge_type": null,
- "charge_id": null,
- "classification": "Felony",
- "deposition": null,
- "defendant": null,
- "plaintiff": null,
- "sentence": "Active Punishment Minimum: 10Y",
- "disposition": "Guilty",
- "probation_status": null,
- "offense_date": "2011-04-22",
- "deposition_date": "2014-05-27",
- "arrest_date": null,
- "charge_date": null,
- "sentence_date": null,
- "disposition_date": "2011-06-02",
- "conviction_date": "2011-06-02",
- "release_date": "2011-06-02",
- "next_court_date": "2011-06-02",
- "court": "Circuit & District Court",
- "plea": null,
- "assessment": null,
- "prison_time": "4 Year(s)",
- "jail_time": "15 Day(s)",
- "probation_time": null,
- "restitution": "220.00"
}
]
}
]
}
Searches Federal District Civil courts to verify felony and misdemeanor records identified by PACER For more information, please see Federal District Civil Search in the Checkr Help Center.
Returns an existing Federal District Civil Search with the input ID.
id required | string ID of the Federal District Civil Search to retrieve. |
$ curl -X GET https://api.checkr.com/v1/federal_district_civil_searches/539fd88c101897f7cd000006 \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
{- "id": "e44aa283528e6fde7d542194",
- "object": "federal_district_civil_search",
- "uri": "/v1/federal_district_civil_searches/625487abdc27f729a9997f50",
- "status": "complete",
- "result": "clear",
- "assessment": "eligible",
- "created_at": "2014-01-18T12:34:00Z",
- "completed_at": "2014-01-18T12:35:30Z",
- "turnaround_time": 90,
- "cancellation_reason": "complete_now_customer_requested",
- "cancellation_reason_description": "Customer requested Complete Now prior to screening completion",
- "records": [
- {
- "id": "e44aa283528e6fde7d542194",
- "case_number": "24323-DA",
- "file_date": null,
- "arresting_agency": null,
- "court_jurisdiction": null,
- "court_of_record": null,
- "full_name": "John Alfred Smith",
- "dob": "1970-01-22",
- "yob": 1970,
- "county": "SUFFOLK",
- "state": "MA",
- "address": {
- "street": "123 Main St.",
- "unit": 2000,
- "city": "San Francisco",
- "state": "CA",
- "zipcode": "90401",
- "country": "US"
}, - "charges": [
- {
- "id": "e44aa283528e6fde7d542194",
- "charge": "Fraud",
- "category": "fraud_and_deception",
- "charge_type": null,
- "charge_id": null,
- "classification": "Felony",
- "deposition": null,
- "defendant": null,
- "plaintiff": null,
- "sentence": "Active Punishment Minimum: 10Y",
- "disposition": "Guilty",
- "probation_status": null,
- "offense_date": "2011-04-22",
- "deposition_date": "2014-05-27",
- "arrest_date": null,
- "charge_date": null,
- "sentence_date": null,
- "disposition_date": "2011-06-02",
- "conviction_date": "2011-06-02",
- "release_date": "2011-06-02",
- "next_court_date": "2011-06-02",
- "court": "Circuit & District Court",
- "plea": null,
- "assessment": null,
- "prison_time": "4 Year(s)",
- "jail_time": "15 Day(s)",
- "probation_time": null,
- "restitution": "220.00"
}
]
}
], - "records_hidden_by_assess": [
- {
- "id": "e44aa283528e6fde7d542194",
- "case_number": "24323-DA",
- "file_date": null,
- "arresting_agency": "DEA Boston Division",
- "court_jurisdiction": null,
- "court_of_record": null,
- "full_name": "John Alfred Smith",
- "dob": "1970-01-22",
- "yob": 1970,
- "county": "SUFFOLK",
- "state": "MA",
- "address": {
- "street": "123 Main St.",
- "unit": 2000,
- "city": "San Francisco",
- "state": "CA",
- "zipcode": "90401",
- "country": "US"
}, - "charges_hidden_by_assess": [
- {
- "id": "e44aa283528e6fde7d542194",
- "charge": "Fraud",
- "category": "fraud_and_deception",
- "charge_type": null,
- "charge_id": null,
- "classification": "Felony",
- "deposition": null,
- "defendant": null,
- "plaintiff": null,
- "sentence": "Active Punishment Minimum: 10Y",
- "disposition": "Guilty",
- "probation_status": null,
- "offense_date": "2011-04-22",
- "deposition_date": "2014-05-27",
- "arrest_date": null,
- "charge_date": null,
- "sentence_date": null,
- "disposition_date": "2011-06-02",
- "conviction_date": "2011-06-02",
- "release_date": "2011-06-02",
- "next_court_date": "2011-06-02",
- "court": "Circuit & District Court",
- "plea": null,
- "assessment": null,
- "prison_time": "4 Year(s)",
- "jail_time": "15 Day(s)",
- "probation_time": null,
- "restitution": "220.00"
}
]
}
], - "filtered_by_positive_adjudication_records": [
- {
- "id": "e44aa283528e6fde7d542194",
- "case_number": "24323-DA",
- "file_date": null,
- "arresting_agency": "DEA Boston Division",
- "court_jurisdiction": null,
- "court_of_record": null,
- "full_name": "John Alfred Smith",
- "dob": "1970-01-22",
- "yob": 1970,
- "county": "SUFFOLK",
- "state": "MA",
- "address": {
- "street": "123 Main St.",
- "unit": 2000,
- "city": "San Francisco",
- "state": "CA",
- "zipcode": "90401",
- "country": "US"
}, - "filtered_by_positive_adjudication_charges": [
- {
- "id": "e44aa283528e6fde7d542194",
- "charge": "Fraud",
- "category": "fraud_and_deception",
- "charge_type": null,
- "charge_id": null,
- "classification": "Felony",
- "deposition": null,
- "defendant": null,
- "plaintiff": null,
- "sentence": "Active Punishment Minimum: 10Y",
- "disposition": "Guilty",
- "probation_status": null,
- "offense_date": "2011-04-22",
- "deposition_date": "2014-05-27",
- "arrest_date": null,
- "charge_date": null,
- "sentence_date": null,
- "disposition_date": "2011-06-02",
- "conviction_date": "2011-06-02",
- "release_date": "2011-06-02",
- "next_court_date": "2011-06-02",
- "court": "Circuit & District Court",
- "plea": null,
- "assessment": null,
- "prison_time": "4 Year(s)",
- "jail_time": "15 Day(s)",
- "probation_time": null,
- "restitution": "220.00"
}
]
}
]
}
County Criminal records make up the majority of criminal records, and are therefore one of the most complete sources for both felony and misdemeanor records. These records are not reported to the federal database, and will therefore not be surfaced in a Federal Criminal Database Search.
The County Criminal Search resource defines the results from a criminal record search in a specific county.
For more information, please see County Criminal Search in the Checkr Help Center.
Returns an existing County Criminal Search with the input ID.
id required | string ID of the County Criminal Search to retrieve. |
$ curl -X GET https://api.checkr.com/v1/county_criminal_searches/539fdcf335644a0ef4000001 \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
{- "id": "e44aa283528e6fde7d542194",
- "object": "county_criminal_search",
- "uri": "/v1/county_criminal_searches/539fdcf335644a0ef4000001",
- "status": "complete",
- "result": "consider",
- "assessment": "eligible",
- "created_at": "2014-01-18T12:34:00Z",
- "completed_at": "2014-01-18T12:35:30Z",
- "turnaround_time": 100800,
- "cancellation_reason": "complete_now_customer_requested",
- "cancellation_reason_description": "Customer requested Complete Now prior to screening completion",
- "estimated_completion_time": "2019-03-13T16:31:07Z",
- "estimated_completion_date": "2019-03-13",
- "county": "SAN FRANCISCO",
- "state": "CA",
- "records": [
- {
- "id": "e44aa283528e6fde7d542194",
- "case_number": "24323-DA",
- "file_date": null,
- "arresting_agency": "DEA Boston Division",
- "court_jurisdiction": null,
- "court_of_record": null,
- "full_name": "John Alfred Smith",
- "dob": "1970-01-22",
- "yob": 1970,
- "county": "SUFFOLK",
- "state": "MA",
- "address": {
- "street": "123 Main St.",
- "unit": 2000,
- "city": "San Francisco",
- "state": "CA",
- "zipcode": "90401",
- "country": "US"
}, - "charges": [
- {
- "id": "e44aa283528e6fde7d542194",
- "charge": "Sell Cocaine",
- "category": "fraud_and_deception",
- "charge_type": null,
- "charge_id": null,
- "classification": "Felony",
- "deposition": null,
- "defendant": "John Alfred Smith",
- "plaintiff": null,
- "sentence": "Active Punishment Minimum: 10Y",
- "disposition": "Guilty",
- "probation_status": null,
- "offense_date": "2011-04-22",
- "deposition_date": "2014-05-27",
- "arrest_date": "2011-04-22",
- "charge_date": null,
- "sentence_date": "2011-06-02",
- "disposition_date": "2011-06-02",
- "conviction_date": "2011-06-02",
- "release_date": "2011-06-02",
- "next_court_date": "2011-06-02",
- "court": "Circuit & District Court",
- "plea": null,
- "assessment": null,
- "prison_time": "4 Year(s)",
- "jail_time": "15 Day(s)",
- "probation_time": null,
- "restitution": "220.00"
}
]
}
], - "filtered_by_positive_adjudication_records": [
- {
- "id": "e44aa283528e6fde7d542194",
- "case_number": "24323-DA",
- "file_date": null,
- "arresting_agency": "DEA Boston Division",
- "court_jurisdiction": null,
- "court_of_record": null,
- "full_name": "John Alfred Smith",
- "dob": "1970-01-22",
- "yob": 1970,
- "county": "SUFFOLK",
- "state": "MA",
- "address": {
- "street": "123 Main St.",
- "unit": 2000,
- "city": "San Francisco",
- "state": "CA",
- "zipcode": "90401",
- "country": "US"
}, - "filtered_by_positive_adjudication_charges": [
- {
- "id": "e44aa283528e6fde7d542194",
- "charge": "Fraud",
- "category": "fraud_and_deception",
- "charge_type": null,
- "charge_id": null,
- "classification": "Felony",
- "deposition": null,
- "defendant": null,
- "plaintiff": null,
- "sentence": "Active Punishment Minimum: 10Y",
- "disposition": "Guilty",
- "probation_status": null,
- "offense_date": "2011-04-22",
- "deposition_date": "2014-05-27",
- "arrest_date": null,
- "charge_date": null,
- "sentence_date": null,
- "disposition_date": "2011-06-02",
- "conviction_date": "2011-06-02",
- "release_date": "2011-06-02",
- "next_court_date": "2011-06-02",
- "court": "Circuit & District Court",
- "plea": null,
- "assessment": null,
- "prison_time": "4 Year(s)",
- "jail_time": "15 Day(s)",
- "probation_time": null,
- "restitution": "220.00"
}
]
}
], - "screening_pointers": [
- [
- "Denver, CO County Search",
- "Kentucky State Search",
- "Widgets-R-Us Employment Address",
- "Harvard University Education Address"
]
]
}
The State Criminal Search returns criminal records from a selected state’s database, the content of which varies by state. Some states include records reported from all counties; some include records only from a few. This search should be used in conjunction with a County Criminal Search, and not as a replacement for the more complete records returned from the County Search.
For more information, please see State Criminal Search in the Checkr Help Center.
Returns an existing State Criminal Search with the input ID.
id required | string ID of the State Criminal Search to retrieve. |
$ curl -X GET https://api.checkr.com/v1/state_criminal_searches/539fdcf335644a0ef4000001 \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
{- "id": "e44aa283528e6fde7d542194",
- "object": "state_criminal_search",
- "uri": "/v1/state_criminal_searches/539fdcf335644a0ef4000001",
- "status": "complete",
- "result": "consider",
- "assessment": "eligible",
- "created_at": "2014-01-18T12:34:00Z",
- "completed_at": "2014-01-18T12:35:30Z",
- "turnaround_time": 100800,
- "cancellation_reason": "complete_now_customer_requested",
- "cancellation_reason_description": "Customer requested Complete Now prior to screening completion",
- "estimated_completion_time": "2014-01-18T12:34:00Z",
- "state": "CA",
- "records": [
- {
- "id": "e44aa283528e6fde7d542194",
- "case_number": "24323-DA",
- "file_date": "2010-02-18",
- "arresting_agency": "San Francisco Police Department",
- "court_jurisdiction": "San Francisco",
- "court_of_record": null,
- "full_name": "John Alfred Smith",
- "dob": "1970-01-22",
- "yob": 1970,
- "county": "SUFFOLK",
- "state": "MA",
- "address": {
- "street": "123 Main St.",
- "unit": 2000,
- "city": "San Francisco",
- "state": "CA",
- "zipcode": "90401",
- "country": "US"
}, - "charges": [
- {
- "id": "e44aa283528e6fde7d542194",
- "charge": "Sell Cocaine",
- "category": "fraud_and_deception",
- "charge_type": null,
- "charge_id": null,
- "classification": "Felony",
- "deposition": null,
- "defendant": "John Alfred Smith",
- "plaintiff": null,
- "sentence": "Active Punishment Minimum: 10Y",
- "disposition": "Guilty",
- "probation_status": null,
- "offense_date": "2011-04-22",
- "deposition_date": "2014-05-27",
- "arrest_date": "2011-04-22",
- "charge_date": null,
- "sentence_date": "2011-06-02",
- "disposition_date": "2011-06-02",
- "conviction_date": "2011-06-02",
- "release_date": "2011-06-02",
- "next_court_date": "2011-06-02",
- "court": "Circuit & District Court",
- "plea": null,
- "assessment": null,
- "prison_time": "4 Year(s)",
- "jail_time": "15 Day(s)",
- "probation_time": null,
- "restitution": "220.00"
}
]
}
], - "filtered_by_positive_adjudication_records": [
- {
- "id": "e44aa283528e6fde7d542194",
- "case_number": "24323-DA",
- "file_date": null,
- "arresting_agency": "DEA Boston Division",
- "court_jurisdiction": null,
- "court_of_record": null,
- "full_name": "John Alfred Smith",
- "dob": "1970-01-22",
- "yob": 1970,
- "county": "SUFFOLK",
- "state": "MA",
- "address": {
- "street": "123 Main St.",
- "unit": 2000,
- "city": "San Francisco",
- "state": "CA",
- "zipcode": "90401",
- "country": "US"
}
}
], - "screening_pointers": [
- [
- "Denver, CO County Search",
- "Kentucky State Search",
- "Widgets-R-Us Employment Address",
- "Harvard University Education Address"
]
]
}
Motor Vehicle Records originate from a state’s Department of Motor Vehicles, and include information related to a person’s driving history, including driver’s license status and restrictions, as well as violations and convictions. Use MVR reports to evaluate a candidate’s driving history and safety record.
Please note that some convictions, such as driving under the influence, may appear only on MVR reports, and not on criminal searches.
For more information, please see Motor Vehicle Records in the Checkr Help Center.
Returns an existing Motor Vehicle Report with the input ID.
id required | string ID of the Motor Vehicle Report to retrieve. |
$ curl -X GET https://api.checkr.com/v1/motor_vehicle_reports/539fd88c101897f7cd000007 \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
{- "id": "e44aa283528e6fde7d542194",
- "object": "motor_vehicle_report",
- "uri": "/v1/motor_vehicle_reports/539fd88c101897f7cd000007",
- "status": "complete",
- "result": "consider",
- "assessment": "eligible",
- "created_at": "2014-01-18T12:34:00Z",
- "completed_at": "2014-01-18T12:35:30Z",
- "turnaround_time": 90,
- "cancellation_reason": "complete_now_customer_requested",
- "cancellation_reason_description": "Customer requested Complete Now prior to screening completion",
- "license_reports": [
- {
- "number": "F2111132",
- "dob": "1980-01-01",
- "state": "CA",
- "status": "valid, expired, not_found",
- "type": "personal, commercial, or non-commercial",
- "class": "C",
- "expiration_date": "2016-07-24",
- "issued_date": "2006-12-03",
- "first_issued_date": "2000-01-14",
- "restrictions": [
- "string"
], - "current_license": true,
- "privilege_to_drive": "valid",
- "violations": [
- {
- "type": "conviction",
- "issued_date": "2011-11-14",
- "conviction_date": "2010-04-11",
- "description": "speeding 15-19 mph",
- "points": 0,
- "city": null,
- "county": "SANTA CLARA",
- "state": "California",
- "ticket_number": "2D55555",
- "disposition": null,
- "category": null,
- "court_name": null,
- "acd_code": null,
- "state_code": null,
- "docket": null
}
], - "accidents": [
- {
- "accident_date": "2009-04-12",
- "description": "property damage",
- "city": null,
- "county": "SAN FRANCISCO",
- "state": null,
- "order_number": "33-435932",
- "points": null,
- "vehicle_speed": null,
- "reinstatement_date": null,
- "action_taken": "police report filed",
- "ticket_number": null,
- "enforcing_agency": "San Francisco PD",
- "jurisdiction": null,
- "severity": null,
- "violation_number": null,
- "license_plate": "6UM6938",
- "fine_amount": null,
- "state_code": null,
- "acd_code": null,
- "injury_accident": false,
- "fatality_accident": false,
- "fatality_count": 0,
- "injury_count": 0,
- "vehicles_involved_count": 3,
- "report_number": null,
- "policy_number": null,
- "group": "property damage",
- "note": "Unless fault is indicated, only the fact of an accident is being reported."
}
], - "suspensions": [
- {
- "description": "ACCUMULATION OF CONVICTIONS OR POINTS",
- "start_date": "2011-11-14",
- "end_date": "2012-03-21",
- "state": "CA"
}
], - "endorsements": [
- "string"
], - "medical_certificates": [
- {
- "status": "CERTIFIED",
- "issued_date": "2011-11-14",
- "expiration_date": "2012-03-21",
- "self_certification": "NON-EXCEPTED INTERSTATE",
- "examiner": {
- "full_name": "Amy Welch Taylor Jr.",
- "license_number": "981736076",
- "license_state": "CT",
- "registration_number": "11111111111"
}
}
]
}
], - "full_name": "John Alfred Smith",
- "license_number": "F2111132",
- "license_state": "CA",
- "previous_license_number": "F2111132",
- "previous_license_state": "CA",
- "license_status": "valid, expired, not_found",
- "license_type": "personal, commercial, or non-commercial",
- "license_class": "C",
- "dob": "1980-01-01",
- "expiration_date": "2016-07-24",
- "covid_extension": true,
- "issued_date": "2006-12-03",
- "first_issued_date": "2000-01-14",
- "inferred_issued_date": null,
- "restrictions": [
- "string"
], - "custom_rules": {
- "rule_key_1": {
- "description": "rule description 1",
- "satisfied": true
}, - "rule_key_2": {
- "description": "rule description 2",
- "satisfied": false
}
}, - "not_found": false,
- "experience_failed": false,
- "type": "standard",
- "privilege_to_drive": "valid",
- "accidents": [
- {
- "accident_date": "2009-04-12",
- "description": "property damage",
- "city": null,
- "county": "SAN FRANCISCO",
- "state": null,
- "order_number": "33-435932",
- "points": null,
- "vehicle_speed": null,
- "reinstatement_date": null,
- "action_taken": "police report filed",
- "ticket_number": null,
- "enforcing_agency": "San Francisco PD",
- "jurisdiction": null,
- "severity": null,
- "violation_number": null,
- "license_plate": "6UM6938",
- "fine_amount": null,
- "state_code": null,
- "acd_code": null,
- "injury_accident": false,
- "fatality_accident": false,
- "fatality_count": 0,
- "injury_count": 0,
- "vehicles_involved_count": 3,
- "report_number": null,
- "policy_number": null,
- "group": "property damage",
- "note": "Unless fault is indicated, only the fact of an accident is being reported."
}
], - "violations": [
- {
- "type": "conviction",
- "issued_date": "2011-11-14",
- "conviction_date": "2010-04-11",
- "description": "speeding 15-19 mph",
- "points": 0,
- "city": null,
- "county": "SANTA CLARA",
- "state": "California",
- "ticket_number": "2D55555",
- "disposition": null,
- "category": null,
- "court_name": null,
- "acd_code": null,
- "state_code": null,
- "docket": null
}
], - "suspensions": [
- {
- "description": "ACCUMULATION OF CONVICTIONS OR POINTS",
- "start_date": "2011-11-14",
- "end_date": "2012-03-21",
- "state": "CA"
}
]
}
A Drug & Alcohol Clearinghouse search provides information about a candidate's drug and alcohol violation history.
The screening includes a query result of Driver Prohibited or Not Prohibited. Further query details, such as the violations themselves, can be accessed via the Checkr Dashboard.
For more information, please see DOT Checks in the Checkr Help Center.
Returns an existing Drug & Alcohol Clearinghouse Search with the input ID.
id required | string ID of the Drug & Alcohol Clearinghouse Search to retrieve. |
$ curl -X GET https://api.checkr.com/v1/drug_alcohol_clearinghouse_searches/e44aa283528e6fde7d542194 \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
{- "id": "e44aa283528e6fde7d542194",
- "report_id": "539fd88c101897f7cd000007",
- "query_result": "Driver Not Prohibited",
- "status": "complete",
- "cancellation_reason": "candidate_missing_consent",
- "cancellation_reason_description": "Candidate consent not provided"
}
Use an Education Verification to verify a candidate’s education history, and highest degree achieved.
For this screening, candidates are asked to supply their degree, major, school, and the state in which the school is located. Checkr then attempts to verify the information. After three failed attempts (itemized in the logs), Checkr generates an exception, and asks the candidate to upload supporting documentation. Once the document is uploaded, the verification process will begin again.
For more information, please see Education Verification in the Checkr Help Center.
Returns an existing Education Verification with the input ID.
id required | string ID of the Education Verification to retrieve. |
$ curl -X GET https://api.checkr.com/v1/education_verifications/59690155331711004e252cd9 \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
{- "id": "e44aa283528e6fde7d542194",
- "object": "education_verification",
- "uri": "/v1/education_verifications/595511af261066005170f47",
- "status": "consider",
- "result": "consider",
- "assessment": "eligible",
- "created_at": "2014-01-18T12:34:00Z",
- "completed_at": "2014-01-18T12:35:30Z",
- "turnaround_time": 603216,
- "cancellation_reason": "complete_now_customer_requested",
- "cancellation_reason_description": "Customer requested Complete Now prior to screening completion",
- "includes_canceled": true,
- "records": [
- {
- "id": "592311d2113adf7e9c9f66b8",
- "result": {
- "verified": false,
- "degrees": [
- {
- "title": "string",
- "majors": "string",
- "major_concentrations": "string",
- "minors": "string",
- "year_awarded": "string"
}
]
}, - "school": {
- "id": "e44aa283528e6fde7d542194",
- "object": "school",
- "uri": "/v1/schools/e44aa283528e6fde7d542194",
- "candidate_id": "83ebeagdec0948690863766f792ead24d61fe3f9",
- "name": "College University",
- "degree": "BA",
- "year_awarded": 2017,
- "major": "Russian Literature",
- "phone": "415-111-1111",
- "minor": "Background Checks",
- "start_date": "2012-09-22",
- "end_date": "2017-05-10",
- "current": false,
- "school_url": "www.collegeuniversity.com",
- "address": {
- "street": "123 Main St.",
- "unit": 2000,
- "city": "San Francisco",
- "state": "CA",
- "zipcode": "90401",
- "country": "US"
}
}, - "events": [
- {
- "text": "started",
- "created_at": "2017-06-29T14:42:47Z",
- "type": "verification_start"
}
], - "status": "consider",
- "cancellation_reason": "customer_requested_complete_now",
- "cancellation_reason_description": "Customer requested Complete Now prior to screening completion"
}
]
}
Use an Employment Verification to verify a candidate’s employment history for the last three employers, or the last seven years.
For this screening, candidates are asked to supply their employment history. Checkr then attempts to verify the information. After three failed attempts (itemized in the logs), Checkr generates an exception, and asks the candidate to upload supporting documentation. Once the document is uploaded, the verification process will begin again.
For more information, please see Employment Verification in the Checkr Help Center.
Returns an existing Employment Verification with the input ID.
id required | string ID of the Employment Verification to retrieve. |
$ curl -X GET https://api.checkr.com/v1/employment_verifications/59690155331711004e252cd8 \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
{- "id": "e44aa283528e6fde7d542194",
- "object": "employment_verification",
- "uri": "/v1/employment_verifications/595511af261066005170f471",
- "status": "consider",
- "result": "consider",
- "assessment": "eligible",
- "created_at": "2014-01-18T12:34:00Z",
- "completed_at": "2014-01-18T12:35:30Z",
- "turnaround_time": 603216,
- "cancellation_reason": "complete_now_customer_requested",
- "cancellation_reason_description": "Customer requested Complete Now prior to screening completion",
- "includes_canceled": true,
- "records": [
- {
- "id": "592311d2113adf7e9c9f66b8",
- "result": {
- "start_date": {
- "verified": true,
- "comments": "2016-06-01",
- "ignored": null
}, - "end_date": {
- "verified": true,
- "comments": "2017-05-01",
- "ignored": null
}, - "position": {
- "verified": true,
- "comments": "Software Development Engineer",
- "ignored": "manual"
}, - "contract_type": {
- "verified": true,
- "comments": "Full Time",
- "ignored": "package"
}, - "salary": {
- "verified": true,
- "comments": "100000",
- "ignored": null
}, - "questions": [
- {
- "sort_number": 1,
- "text": "What is the documented reason for the employee's departure?",
- "response": "They resigned."
}
]
}, - "employer": {
- "id": "e44aa283528e6fde7d542194",
- "object": "employer",
- "uri": "/v1/candidates/e44aa283528e6fde7d542194/employers/ca27df84be5b50dfa7ee1cda",
- "candidate_id": "xxx",
- "name": "Checkr",
- "position": "Software Engineer",
- "salary": 10000,
- "contract_type": "full_time",
- "do_not_contact": false,
- "start_date": "2016-06-01",
- "end_date": "2017-05-01",
- "employer_url": "www.employer.com",
- "address": {
- "street": "123 Main St.",
- "unit": 2000,
- "city": "San Francisco",
- "state": "CA",
- "zipcode": "90401",
- "country": "US"
}, - "manager": {
- "name": "Joe Smith",
- "title": "Engineering Manager",
- "email": "joesmith@checkr.co",
- "phone": "212-555-1234"
}
}, - "events": [
- {
- "text": "started",
- "created_at": "2017-06-29T14:42:44Z",
- "type": "verification_start"
}
], - "status": "consider",
- "cancellation_reason": "customer_requested_complete_now",
- "cancellation_reason_description": "Customer requested Complete Now prior to screening completion"
}
]
}
Use a Personal Reference Verification to verify a candidate’s personal credentials. For this screening, candidates are asked to supply a personal reference. Checkr then contacts the personal reference and asks predefined questions to confirm their credentials. For more information, please see Personal and Professional Reference Checks.
Returns an existing Personal Reference Verification with the input ID.
id required | string ID of the Personal Reference Verification to retrieve. |
$ curl -X GET https://api.checkr.com/v1/personal_reference_verifications/642f279b0ea616002e474daa \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
{- "id": "642f279b0ea616002e474daa",
- "object": "personal_reference_verifications",
- "uri": "/v1/personal_reference_verifications/642f279b0ea616002e474daa",
- "status": "consider",
- "result": "consider",
- "assessment": "eligible",
- "created_at": "2014-01-18T12:34:00Z",
- "completed_at": "2014-01-18T12:35:30Z",
- "turnaround_time": 42,
- "cancellation_reason": "complete_now_customer_requested",
- "cancellation_reason_description": "Customer requested Complete Now prior to screening completion",
- "name": "John Smith",
- "email": "john.smith@gmail.com",
- "phone": 5555555555,
- "relationship": "Friend",
- "questions": [
- {
- "question": "How long have you known the applicant?",
- "answer": "We have known each other for about ten years."
}
]
}
Use a Professional Reference Verification to verify a candidate’s professional credentials. For this screening, candidates are asked to supply a professional reference. Checkr then contacts the professional reference and asks predefined questions to confirm their credentials. For more information, please see Personal and Professional Reference Checks.
Returns an existing Professional Reference Verification with the input ID.
id required | string ID of the Professional Reference Verification to retrieve. |
$ curl -X GET https://api.checkr.com/v1/professional_reference_verifications/642f279b0ea616002e474daa \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
{- "id": "642f279b0ea616002e474daa",
- "object": "professional_reference_verifications",
- "uri": "/v1/professional_reference_verifications/642f279b0ea616002e474daa",
- "status": "consider",
- "result": "consider",
- "assessment": "eligible",
- "created_at": "2014-01-18T12:34:00Z",
- "completed_at": "2014-01-18T12:35:30Z",
- "turnaround_time": 42,
- "cancellation_reason": "complete_now_customer_requested",
- "cancellation_reason_description": "Customer requested Complete Now prior to screening completion",
- "name": "John Smith",
- "email": "john.smith@gmail.com",
- "phone": 5555555555,
- "relationship": "Manager",
- "questions": [
- {
- "question": "How long have you known the applicant?",
- "answer": "We have known each other for about ten years."
}
]
}
Use a Professional License Verification to verify a candidate's professional credentials.
Returns an existing Professional License Verification with the input ID.
id required | string ID of the Professional License Verification to retrieve. |
{- "id": "e44aa283528e6fde7d542194",
- "object": "professional_license_verification",
- "uri": "/v1/professional_license_verifications/5ee1b0c080c74df951ce6a59",
- "status": "consider",
- "result": "consider",
- "assessment": "eligible",
- "created_at": "2014-01-18T12:34:00Z",
- "completed_at": "2014-01-18T12:35:30Z",
- "turnaround_time": 603216,
- "cancellation_reason": "complete_now_customer_requested",
- "cancellation_reason_description": "Customer requested Complete Now prior to screening completion",
- "documents": [
- {
- "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"
}
], - "certifications": [
- {
- "result": {
- "certification_issued_to": "Jersey John Smith",
- "certification_issuer": "California: Care Providers",
- "certification_issuer_region": "CA",
- "certification_expiration": "01/10/2019",
- "verified_by": "partner",
- "sub_results": [
- {
- "name": "license_number",
- "value": "B1234567"
}
], - "sub_checks": [
- {
- "name": "not_expired",
- "status": "consider"
}, - {
- "name": "data_consistency",
- "status": "clear"
}, - {
- "name": "in_good_standing",
- "status": "clear"
}, - {
- "name": "found",
- "status": "clear"
}
]
}, - "input": {
- "certification_issued_to": "Jersey John Smith",
- "certification_issuer": "California: Care Providers",
- "license_number": "B1234567",
- "license_type": "Nurse",
- "additional_text": "License expires on 01-01-2050"
}, - "candidate_documents": [
- {
- "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"
}
]
}
]
}
In countries where third party access to criminal record information is restricted, Adverse Media Checks may be performed to access private databases, public sanctions lists, media sources, and other public and private record repositories. Refer to International Screenings for more details.
Returns an existing International Adverse Media Search with the input ID.
id required | string ID of the International Adverse Media Search to retrieve. |
$ curl -X GET https://api.checkr.com/v1/international_adverse_media_searches/41007cffefb435cf7d701f75d8b86c \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
{- "id": "41007cffefb435cf7d701f75d8b86c",
- "object": "international_adverse_media_search",
- "uri": "/v1/international_adverse_media_searches/41007cffefb435cf7d701f75d8b86c",
- "status": "complete",
- "result": "clear",
- "created_at": "2014-01-18T12:34:00Z",
- "completed_at": "2014-01-18T12:35:30Z",
- "turnaround_time": 90,
- "cancellation_reason": "complete_now_customer_requested",
- "cancellation_reason_description": "Customer requested Complete Now prior to screening completion",
- "country": "FR",
}
Criminal records check in supported countries. Criminal data is accessed from the appropriate database or agency. Refer to International Screenings for more details.
Returns an existing International Criminal Search with the input ID.
id required | string ID of the International Criminal Search to retrieve. |
$ curl -X GET https://api.checkr.com/v1/international_criminal_searches/41007cffefb435cf7d701f75d8b86d \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
{- "id": "41007cffefb435cf7d701f75d8b86d",
- "object": "international_criminal_search",
- "uri": "/v1/international_criminal_searches/41007cffefb435cf7d701f75d8b86d",
- "status": "complete",
- "result": "clear",
- "created_at": "2014-01-18T12:34:00Z",
- "completed_at": "2014-01-18T12:35:30Z",
- "turnaround_time": 90,
- "cancellation_reason": "complete_now_customer_requested",
- "cancellation_reason_description": "Customer requested Complete Now prior to screening completion",
- "records": [
- {
- "id": "e44aa283528e6fde7d542194",
- "case_number": "24323-DA",
- "file_date": null,
- "arresting_agency": null,
- "court_jurisdiction": null,
- "court_of_record": null,
- "full_name": "John Alfred Smith",
- "dob": "1970-01-22",
- "yob": 1970,
- "county": "SUFFOLK",
- "state": "MA",
- "address": {
- "street": "123 Champs-Élysées",
- "unit": 2000,
- "city": "Paris",
- "state": "IDF",
- "zipcode": "75008",
- "country": "FR"
}, - "charges": [
- {
- "id": "e44aa283528e6fde7d542194",
- "charge": "Fraud",
- "category": "fraud_and_deception",
- "charge_type": null,
- "charge_id": null,
- "classification": "Felony",
- "deposition": null,
- "defendant": null,
- "plaintiff": null,
- "sentence": "Active Punishment Minimum: 10Y",
- "disposition": "Guilty",
- "probation_status": null,
- "offense_date": "2011-04-22",
- "deposition_date": "2014-05-27",
- "arrest_date": null,
- "charge_date": null,
- "sentence_date": null,
- "disposition_date": "2011-06-02",
- "conviction_date": "2011-06-02",
- "release_date": "2011-06-02",
- "next_court_date": "2011-06-02",
- "court": "Circuit & District Court",
- "plea": null,
- "assessment": null,
- "prison_time": "4 Year(s)",
- "jail_time": "15 Day(s)",
- "probation_time": null,
- "restitution": "220.00"
}
]
}
], - "country": "FR",
}
The verification of academic status of any educational level such as high school, college and post-grad may include institution name, dates of attendance, graduation/conferred date, degree obtained, major, minor, honors and relevant awards. Reasonable attempts will be made to search available industry databases and international educational institutions. Refer to International Screenings for more details.
Returns an existing International Education Verificaiton with the input ID.
id required | string ID of the International Education Verificaiton to retrieve. |
$ curl -X GET https://api.checkr.com/v1/international_education_verifications/41007cffefb435cf7d701f75d8b86e \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
{- "id": "41007cffefb435cf7d701f75d8b86c",
- "object": "international_education_verification",
- "uri": "/v1/international_education_verifications/41007cffefb435cf7d701f75d8b86c",
- "status": "complete",
- "result": "clear",
- "created_at": "2014-01-18T12:34:00Z",
- "completed_at": "2014-01-18T12:35:30Z",
- "turnaround_time": 603216,
- "cancellation_reason": "complete_now_customer_requested",
- "cancellation_reason_description": "Customer requested Complete Now prior to screening completion",
- "records": [
- {
- "id": "592311d2113adf7e9c9f66b8",
- "result": {
- "verified": false
}, - "school": {
- "id": "e44aa283528e6fde7d542194",
- "object": "school",
- "uri": "/v1/schools/e44aa283528e6fde7d542194",
- "candidate_id": "83ebeagdec0948690863766f792ead24d61fe3f9",
- "name": "College University",
- "degree": "BA",
- "year_awarded": 2017,
- "major": "Russian Literature",
- "phone": "415-111-1111",
- "minor": "Background Checks",
- "start_date": "2012-09-22",
- "end_date": "2017-05-10",
- "current": false,
- "school_url": "www.collegeuniversity.com",
- "address": {
- "street": "123 Champs-Élysées",
- "unit": 2000,
- "city": "Paris",
- "state": "IDF",
- "zipcode": "75008",
- "country": "FR"
}
}, - "events": [
- {
- "text": "started",
- "created_at": "2017-06-29T14:42:47Z",
- "type": "verification_start"
}
], - "status": "consider",
- "country": "FR",
}
]
}
Verification of previous employment history may include employer’s name, dates of employment, position/title, reason for leaving, eligibility for rehire, and comments. Reasonable attempts will be made to verify available government agencies and employment databases. Email verification, and phone verification may be used in countries where the records of former employers are not available in searchable form, and where contacting the supervisor or manager is common practice. Refer to International Screenings for more details.
Returns an existing International Employment Verification with the input ID.
id required | string ID of the International Employment Verification to retrieve. |
$ curl -X GET https://api.checkr.com/v1/international_education_verifications/41007cffefb435cf7d701f75d8b86f \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
{- "id": "41007cffefb435cf7d701f75d8b86f",
- "object": "international_employment_verification",
- "uri": "/v1/international_employment_verifications/41007cffefb435cf7d701f75d8b86f",
- "status": "complete",
- "result": "clear",
- "created_at": "2014-01-18T12:34:00Z",
- "completed_at": "2014-01-18T12:35:30Z",
- "turnaround_time": 603216,
- "cancellation_reason": "complete_now_customer_requested",
- "cancellation_reason_description": "Customer requested Complete Now prior to screening completion",
- "records": [
- {
- "id": "592311d2113adf7e9c9f66b8",
- "result": {
- "start_date": {
- "verified": true,
- "comments": "2016-06-01",
- "ignored": null
}, - "end_date": {
- "verified": true,
- "comments": "2017-05-01",
- "ignored": null
}, - "position": {
- "verified": true,
- "comments": "Software Development Engineer",
- "ignored": "manual"
}, - "contract_type": {
- "verified": true,
- "comments": "Full Time",
- "ignored": "package"
}, - "salary": {
- "verified": true,
- "comments": "100000",
- "ignored": null
}, - "questions": [
- {
- "sort_number": 1,
- "text": "What is the documented reason for the employee's departure?",
- "response": "They resigned."
}
]
}, - "employer": {
- "id": "e44aa283528e6fde7d542194",
- "object": "employer",
- "uri": "/v1/candidates/e44aa283528e6fde7d542194/employers/ca27df84be5b50dfa7ee1cda",
- "candidate_id": "xxx",
- "name": "Checkr",
- "position": "Software Engineer",
- "salary": 10000,
- "contract_type": "full_time",
- "do_not_contact": false,
- "start_date": "2016-06-01",
- "end_date": "2017-05-01",
- "employer_url": "www.employer.com",
- "address": {
- "street": "123 Champs-Élysées",
- "unit": 2000,
- "city": "Paris",
- "state": "IDF",
- "zipcode": "75008",
- "country": "FR"
}, - "manager": {
- "name": "Joe Smith",
- "title": "Engineering Manager",
- "email": "joesmith@checkr.co",
- "phone": "212-555-1234"
}
}, - "events": [
- {
- "text": "started",
- "created_at": "2017-06-29T14:42:44Z",
- "type": "verification_start"
}
], - "status": "consider",
- "country": "FR",
}
]
}
A comprehensive search of multiple U.S. and International government watchlists which include the FBI’s Most Wanted list, Interpol's Most Wanted lists, Office of Foreign Asset Control Sanction lists, Denied Persons lists, Department of State Sanction lists, and the Specially Designated Nationals List. Refer to International Screenings for more details.
Returns an existing International Global Watchlist Search with the input ID.
id required | string ID of the International Global Watchlist Search to retrieve. |
$ curl -X GET https://api.checkr.com/v1/international_global_watchlist_searches/41007cffefb435cf7d701f75d8b87a \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
{- "id": "41007cffefb435cf7d701f75d8b87a",
- "object": "international_global_watchlist_search",
- "uri": "/v1/international_global_watchlist_searches/41007cffefb435cf7d701f75d8b87a",
- "status": "complete",
- "result": "clear",
- "created_at": "2014-01-18T12:34:00Z",
- "completed_at": "2014-01-18T12:35:30Z",
- "turnaround_time": 90,
- "cancellation_reason": "complete_now_customer_requested",
- "cancellation_reason_description": "Customer requested Complete Now prior to screening completion",
- "country": "FR",
}
Verifies that the candidate’s passport, national ID or driver’s license is authentic and validly in circulation. This check provides a multi-level validation process by inspecting document data and positioning for authenticity, scanning the Machine Readable Zone (if available), and cross-checking the information provided against government databases to discover if the document is stolen, lost, expired or invalid. Refer to International Screenings for more details.
Returns an existing International Identity Document Validation with the input ID.
id required | string ID of the International Identity Document Validation to retrieve. |
$ curl -X GET https://api.checkr.com/v1/international_identity_document_validations/41007cffefb435cf7d701f75d8b87b \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
{- "id": "41007cffefb435cf7d701f75d8b87b",
- "object": "international_identity_document_validation",
- "uri": "/v1/international_identity_document_validations/41007cffefb435cf7d701f75d8b87b",
- "status": "complete",
- "result": "clear",
- "created_at": "2014-01-18T12:34:00Z",
- "completed_at": "2014-01-18T12:35:30Z",
- "turnaround_time": 90,
- "cancellation_reason": "complete_now_customer_requested",
- "cancellation_reason_description": "Customer requested Complete Now prior to screening completion",
}
Checks the validity of a driver license and where available, may include a detailed history of the candidate’s driving violations or license conditions. Canada only at this time. Refer to International Screenings for more details.
Returns an existing International Motor Vehicle Report with the input ID.
id required | string ID of the International Motor Vehicle Report to retrieve. |
$ curl -X GET https://api.checkr.com/v1/international_motor_vehicle_reports/41007cffefb435cf7d701f75d8b86d \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
{- "id": "41007cffefb435cf7d701f75d8b86d",
- "object": "international_motor_vehicle_report",
- "uri": "/v1/international_motor_vehicle_reports/41007cffefb435cf7d701f75d8b86d",
- "status": "complete",
- "result": "clear",
- "created_at": "2014-01-18T12:34:00Z",
- "completed_at": "2014-01-18T12:35:30Z",
- "turnaround_time": 90,
- "cancellation_reason": "complete_now_customer_requested",
- "cancellation_reason_description": "Customer requested Complete Now prior to screening completion",
- "country": "CA",
- "license_reports": [
- {
- "license_status": "VALID",
- "actual_license_class": 1,
- "is_valid_license_class": true,
- "license_infos": [
- {
- "license_number": "ABC12345",
- "country": "CA",
- "subdivision": "CA-AB",
- "license_class": "G1",
- "expiration_date": "2030-01-01T00:00:00.000Z",
- "is_current": true
}
], - "violations": [
- {
- "issued_date": "2050-01-01T00:00:00.000Z",
- "description": "HIT AND RUN"
}
]
}
]
}
Searches databases for records of adverse actions against individuals and entities in the healthcare field. For more information, please see FACIS in the Checkr Help Center.
Returns an existing FACIS Search with the input ID.
id required | string ID of the Facis Search to retrieve. |
$ curl -X GET https://api.checkr.com/v1/facis_searches/539fd88c101897f7cd000006 \ -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
{- "status": "complete",
- "result": "clear",
- "cancellation_reason": "complete_now_customer_requested",
- "cancellation_reason_description": "Customer requested Complete Now prior to screening completion",
- "id": "e44aa283528e6fde7d542194",
- "created_at": "2014-01-18T12:34:00Z",
- "completed_at": "2014-01-18T12:35:30Z",
- "turnaround_time": 345600,
- "object": "facis_search",
- "subtype": "1",
- "records": [
- {
- "id": "e44aa283528e6fde7d542194",
- "dob": "1970-01-22",
- "authority": "California Department of Health Care Services",
- "database_registry": "California Department of Health Care Services, Medi-Cal - Suspended and Ineligible Provider List",
- "sactions": [
- {
- "saction": "Suspended and Ineligible",
- "entry_date": "2019-07-11",
- "acquisition_date": "2019-06-28",
- "publication_date": "2019-01-18",
- "case_number": "19-0278"
}
], - "full_name": "John Alfred Smith"
}
]
}
Before you can start using Checkr's I9 verification endpoints please complete first adding Form I-9 to your account. A step by step guide can be found at Checkr Help Center
The Forms I-9 resource provides all information about Forms I-9. It also allows to create a new Form I-9, retrieves details about ongoing I-9s (creating a CSV file) and also makes the PDF files for completed I-9s available.
Retrieves all I-9s for the authenticated Checkr account.
order_by | string Returns records listed by If neither is specified, records will be ordered by start_date. Example: order_by=full_name |
order | string Returns records listed in ascending or descending order of the order_by parameter. If neither is specified, records will be listed in descending order. Example: order=asc |
page | integer Specifies the page number to retrieve. |
per_page | integer Default: 25 Indicates how many records each page should contain. |
$ curl -X GET https://api.checkr.com/v1/i9/forms_i9?order_by=start_date&order=desc&page=1&per_page=25 \ -U YOUR_SECRET_API_KEY:
{- "object": "list",
- "count": 1,
- "data": [
- {
- "id": "1a16ef5f9c1f1df045e74bb4",
- "object": "form_i9",
- "uri": "v1/forms_i9/1a16ef5f9c1f1df045e74bb4",
- "candidate_id": "3de7e278beb24d14a3785e2dd02cca49",
- "order_progress": "section_1_incomplete",
- "open_tasks": "complete_section_2",
- "open_tasks_url": "",
- "start_date": "2023-04-29",
- "worksite_id": "8046067e32ad6b25a9078735",
- "worksite_uri": "v1/i9/worksites/8046067e32ad6b25a9078735",
- "workflow_type": "remote_section_1_only",
- "authorized_representative_first_name": "Lee",
- "authorized_representative_last_name": "Perry",
- "authorized_representative_email": "lee.perry@domain.com",
- "created_at": "2023-04-29T16:21:11Z"
}
]
}
Creates a new Form I-9 resource. This resource allow the creation of a single Form I-9 and also the creation of a bulk of Forms I-9 in one request.
candidate_id required | string Candidate resource Id. |
email required | string Candidate email address. |
worksite_id required | string Worksite resource Id. |
workflow_type required | string Workflow type. For additional insights into workflow types, please consider reviewing the Form I-9 definitions. |
start_date required | string Candidate start date. |
authorized_representative_first_name | string First name of authorized representative. |
authorized_representative_last_name | string Last name of authorized representative. |
authorized_representative_email | string Email address of authorized representative. |
$ curl -X POST https://api.checkr.com/v1/i9/forms_i9 \ -U YOUR_SECRET_API_KEY: \ -H "Content-Type: application/json" \ -d '{ "candidate_id": "3de7e278beb24d14a3785e2dd02cca49", "email": "john.doe@example.com", "start_date": "2023-04-29", "worksite_id": "8046067e32ad6b25a9078735", "workflow_type": "remote_section_1_only", "authorized_representative_first_name": "Lee", "authorized_representative_last_name": "Perry", "authorized_representative_email": "lee.perry@domain.com" }'
{- "id": "1a16ef5f9c1f1df045e74bb4",
- "object": "form_i9",
- "uri": "v1/forms_i9/1a16ef5f9c1f1df045e74bb4",
- "candidate_id": "3de7e278beb24d14a3785e2dd02cca49",
- "order_progress": "section_1_incomplete",
- "open_tasks": "complete_section_2",
- "open_tasks_url": "",
- "start_date": "2023-04-29",
- "worksite_id": "8046067e32ad6b25a9078735",
- "worksite_uri": "v1/i9/worksites/8046067e32ad6b25a9078735",
- "workflow_type": "remote_section_1_only",
- "authorized_representative_first_name": "Lee",
- "authorized_representative_last_name": "Perry",
- "authorized_representative_email": "lee.perry@domain.com",
- "created_at": "2023-04-29T16:21:11Z"
}
Retrieves an existing Form I-9.
id required | string ID of the Form I9 |
$ curl -X GET https://api.checkr.com/v1/i9/forms_i9/1a16ef5f9c1f1df045e74bb4 \ -H YOUR_SECRET_API_KEY:
{- "id": "1a16ef5f9c1f1df045e74bb4",
- "object": "form_i9",
- "uri": "v1/forms_i9/1a16ef5f9c1f1df045e74bb4",
- "candidate_id": "3de7e278beb24d14a3785e2dd02cca49",
- "order_progress": "section_1_incomplete",
- "open_tasks": "complete_section_2",
- "open_tasks_url": "",
- "start_date": "2023-04-29",
- "worksite_id": "8046067e32ad6b25a9078735",
- "worksite_uri": "v1/i9/worksites/8046067e32ad6b25a9078735",
- "workflow_type": "remote_section_1_only",
- "authorized_representative_first_name": "Lee",
- "authorized_representative_last_name": "Perry",
- "authorized_representative_email": "lee.perry@domain.com",
- "created_at": "2023-04-29T16:21:11Z"
}
Retrieves a Form I-9 PDF file associated with the Form I-9 ID.
This endpoint returns a pre-signed S3 URL, valid for 5 minutes.
id required | string ID of the Form I9 |
$ curl -X GET https://api.checkr.com/v1/i9/forms_i9/1a16ef5f9c1f1df045e74bb4/pdf \ -H YOUR_SECRET_API_KEY:
https://api.checkr.com/key_1?X-Amz-Credential=xyz%2F20231002%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20231002T182721Z&x-id=GetObject&X-Amz-Signature=00fa239977fddb97a5e66f899ac41c34726bb9fb34167c60aa97762a1360eda7
The User resource includes user information and role assignments. Users can be invited and assigned roles from the Dashboard.
Returns a list with all existing Worksites for the authenticated Checkr account.
order_by | string Returns records ordered by If neither is specified, records will not be ordered. Example: order_by=street_line1 |
order | string Returns records listed in ascending or descending order of the order_by parameter. If neither is specified, records will be listed in descending order. Example: order=desc |
$ curl -X GET https://api.checkr.com/v1/i9/worksites?order_by=state&order=desc \ -U YOUR_SECRET_API_KEY:
{- "object": "list",
- "count": 1,
- "data": [
- {
- "id": "8046067e32ad6b25a9078735",
- "name": "Head Office",
- "street_line1": "Some Rd",
- "street_line2": "Some Rd 2",
- "city": "San Francisco",
- "state": "CA",
- "zip_code": "66554",
- "everify_status": "not_determined"
}
]
}
Create new Worksites for the authenticated account.
name required | string Worksite name. |
street_line1 required | string Line one of Worksite address. |
street_line2 | string Line two of Worksite address. |
city required | string City of Worksite. |
state required | string State of Worksite. |
zip_code required | string ZIP Code of Worksite. |
$ curl -X POST https://api.checkr.com/v1/i9/worksites \ -U YOUR_SECRET_API_KEY: \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -d '{ "name": "Head Office", "street_line1": "Some Rd", "street_line2": "Some Rd 2", "city": "San Francisco", "state": "California", "zip_code": "66554" }'
{- "id": "8046067e32ad6b25a9078735",
- "name": "Head Office",
- "street_line1": "Some Rd",
- "street_line2": "Some Rd 2",
- "city": "San Francisco",
- "state": "CA",
- "zip_code": "66554",
- "everify_status": "not_determined"
}
Returns a specified Worksite for the authenticated Checkr account.
id required | string Worksite resource Id |
$ curl -X GET https://api.checkr.com/v1/i9/worksites/8046067e32ad6b25a9078735 \ -U YOUR_SECRET_API_KEY:
{- "id": "8046067e32ad6b25a9078735",
- "name": "Head Office",
- "street_line1": "Some Rd",
- "street_line2": "Some Rd 2",
- "city": "San Francisco",
- "state": "CA",
- "zip_code": "66554",
- "everify_status": "not_determined"
}
Update Worksite information
id required | string Worksite resource Id |
name | string Worksite name. |
street_line1 | string Line one of Worksite address. |
street_line2 | string Line two of Worksite address. |
city | string City of Worksite. |
state | string State of Worksite. |
zip_code | string ZIP Code of Worksite. |
everify_status | string Worksite E-Verify Status. |
$ curl -X PUT https://api.checkr.com/v1/i9/worksites/79265751d363a140106fec15 \ -U YOUR_SECRET_API_KEY: \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -d '{ "name": "Updated Worksite", "street_line1": "Some Rd first", "street_line2": "Some Rd second", "city": "San Francisco", "state": "California", "zip_code": "66554", "everify_status": "inactive" }'
{- "id": "79265751d363a140106fec15",
- "name": "Updated Worksite",
- "street_line1": "Some Rd first",
- "street_line2": "Some Rd second",
- "city": "San Francisco",
- "state": "California",
- "zip_code": "66554",
- "everify_status": "inactive"
}
Deletes specified Worksite. If there are at least one Form I-9 associated with a Worksite, this Worksite cannot be deleted.
id required | string Worksite resource Id |
$ curl -X DELETE https://api.checkr.com/v1/i9/worksites/8046067e32ad6b25a9078735 \ -U YOUR_SECRET_API_KEY:
null