Using the API

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 POST https://api.checkr.com/v1/candidates \
  -H "Content-Type: application/json" \
  -u YOUR_API_KEY: \
  -d '{"first_name": "John", "last_name": "Smith", "email": "john.smith@gmail.com"}'

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/reports/59b650f567e1dd0f01422b92?include=candidate,ssn_trace,county_criminal_searches" \
  -u YOUR_API_KEY:

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.

curl -X GET "https://api.checkr.com/v1/candidates?page=2&per_page=25" \
  -u YOUR_API_KEY:

Paginated responses include the following attributes:

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:

Here are some recommendations to stay under the limit:

• Subscribe to Checkr webhooks to get updates about a report's activity instead of polling.
• If you do anticipate situations where you could exceed the limit, we recommend using an exponential backoff (wait 2 seconds, then 5, then 10, then 30, etc.) and retrying the API call.

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.

curl -X POST https://api.checkr.com/v1/reports \
  -u YOUR_API_KEY: \
  -H 'Idempotency-Key: 40b23921-c005-4ec7-832a-3ae023dbbc11' \
  -d package=driver_pro \
  -d candidate_id=be529e5d8cc5ad26e655ce89 \
  -d consent_document_ids[]=b73f89e14b393979857806f9

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.

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's product incorporates SSN field controls designed to not accept SSNs with the following characteristics:

• SSNs without exactly 9 numeric characters
• SSNs that start with 666 (666-34-3768)
• SSNs that start with 9 (967-65-4325)
• SSNs that are a single digit (111-11-1111)
• SSNs that are sequential digits (123-45-6789)

The Checkr API validates submitted email addresses using the industry standard RFC 5322. The string length must be <=255, and the domain must be valid and configured to accept email. (For example: gmail.com is a valid domain, while gmeil.con is not.)

To avoid errors, we suggest that you validate emails used in your candidate creation requests.

Checkr's API offers a number of error codes to facilitate your building and troubleshooting. Some common error codes include:

Screenings can be canceled due to various scenarios. Here is a list of the current cancellation reasons and their descriptions.

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.

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.

Represents the current status of the I-9/E-Verify process.

Checkr has compiled the following table of valid driver license number input per jurisdiction. To avoid errors, we suggest that you implement driver license number validation for both the Candidates and Driver Licenses endpoints.