## Getting Started

## Get Credentialed

Before you can request data from this API, you must first work with a Checkr Account Executive or Customer Success representative to set up and credential your account. You will receive a `client_id` and `client_secret` for the OAuth client-credentials flow described below.

Best practices for securing your API credentials:

- Do not store your credentials in your codebase or commit them to version control. Instead, securely store them only in your production environment, such as in environment variables.
- Do not expose credentials on the client side. All token exchange and API requests should be made from the server side, and only necessary data should be passed to the client.
- If credentials are compromised, contact Checkr immediately to revoke them. Checkr will expire the current credentials and your Account Executive or Customer Success Representative will issue new ones.


## Authentication

Protected endpoints require an OAuth 2.0 **Bearer** access token obtained with the
**client credentials** grant (machine-to-machine). Checkr issues you a
`client_id` and `client_secret` after you are credentialed — these are not end-user
login credentials.

Exchange them at [`POST /accounts/token`](/v1#operation/post-accounts-token)
for a JWT. Tokens expire in **1 hour** (`expires_in: 3600`); cache the token and
request a new one when it expires or a request returns `401` (this public token
endpoint does not issue refresh tokens). Rely on the returned `expires_in` rather
than hard-coding the lifetime.

Best practices:

- Store `client_id` / `client_secret` only in your server environment (never in
client-side code or git).
- Treat Pilot credentials like production secrets (see [Accounts](/accounts)).
- If credentials are compromised, contact Checkr immediately to rotate them.


### OAuth 2.0 client credentials (overview)

This is **not** the authorization-code (user login) flow. There is no browser redirect
or resource-owner password grant on the public API.

### Obtaining an access token

#### Step 1: Access token request

#### Step 2: Access token response

A successful response is **HTTP 200** with the token payload:

```json
{
  "access_token": "eyJhb...(something long)...qJFlg",
  "scope": "read:account create:account delete:account",
  "expires_in": 3600,
  "token_type": "Bearer"
}
```

### Using the access token

Send the token on every protected request:

Product endpoints (checks, profiles, and so on) authorize a valid Bearer token for
your account plus an enabled product configuration. Some account/user management
routes also require specific OAuth scopes on the token.

### Error handling

- **`400`** — for example an unsupported `grant_type`. Body uses this API's standard
JSON:API-style `errors` array.
- **`401`** — invalid client credentials or an Auth0 rejection. Body is Auth0's OAuth
error object:


```json
{
  "error": "access_denied",
  "error_description": "Unauthorized"
}
```

- **`500`** — the authentication provider returned an unexpected or unparsable
response. Body uses this API's standard JSON:API-style `errors` array.


## Webhooks

Our API uses webhooks to notify your application about asynchronous events, primarily when certain checks or verifications are completed. This allows you to receive results without needing to poll our API continuously.

### Configuration

Configure webhook endpoints in the dashboard under **Configuration → Webhooks**, or with your Checkr Account Executive. The destination URL is set per product configuration, so an account running more than one webhook-enabled product must configure each product it wants webhooks for. Dashboard access requires an admin role; if you do not see the Webhooks tab, contact your Account Executive to set up or update the URL. You may optionally provide a dedicated shared secret for signature verification; if you do not, we sign webhooks with your account's OAuth `client_secret`.

Receiving results for `driver_checks` (both `driver_license_status` and `motor_vehicle_report`) **requires** a configured webhook endpoint.

The results are delivered asynchronously via a webhook payload once the check/verification is complete. See the specific event schemas defined under the callbacks for the respective POST operations:

- `POST /driver_checks`: `driver-license-status-completed-event-body`, `motor-vehicle-report-completed-event-body`


### Payload Signing & Verification (HMAC-SHA256)

Every webhook payload is signed with HMAC-SHA256 so you can verify integrity and authenticity. **Signing is always applied** — it is not optional. What *is* optional is configuring a dedicated signing key; by default we use your account's OAuth `client_secret` (the same secret used for the client-credentials token flow).

**How it Works:**

- We generate a signature for each webhook event payload using a shared secret.
- By default, that secret is your account's OAuth `client_secret`.
- Optionally, you can configure a dedicated `signature_key` on the product configuration (via your Account Executive). When set, that key is used instead of `client_secret`. A dedicated key is recommended so a compromised webhook endpoint does not expose your OAuth credential.
- The signature is calculated using the HMAC-SHA256 algorithm on the **raw JSON payload** of the webhook request body.
- The resulting signature (as a hexadecimal string) is included in the webhook request's HTTP headers, under the `X-Checkr-Signature` header with the value `sha256={signature}`


**Verifying the Signature (Recommended):**
You should verify this signature on your end to confirm that the payload was sent by Checkr and hasn't been tampered with.

**Verification Steps:**

1. Extract the signature from the `X-Checkr-Signature` (or the specific header name provided to you) header of the incoming request.
2. Read the **raw request body**. It is crucial *not* to parse and re-serialize the JSON before verification, as minor changes (like whitespace or key order) can invalidate the signature.
3. Compute the HMAC-SHA256 hash of the raw payload string using your signing key (your dedicated `signature_key`, or your OAuth `client_secret` if none is configured).
4. Convert the computed hash to its hexadecimal representation.
5. Compare the signature extracted from the header with your computed signature. Use a timing-safe comparison function provided by your language/framework to prevent timing attacks.


**Code Examples for Verification:**

*Ruby:*

```ruby
require 'openssl'
# For secure_compare, typically available in Rails/ActiveSupport
require 'active_support/security_utils'

# Assuming 'request' is your HTTP request object
# and 'SIGNATURE_KEY' is your dedicated signing key, or your OAuth
# client_secret if no dedicated signature_key is configured
provided_signature = request.headers['X-Checkr-Signature']&.split('=')&.last
raise 'signature missing' unless provided_signature

# Ensure you get the raw body, not parsed JSON
payload_body = request.raw_post

expected_signature = OpenSSL::HMAC.hexdigest('SHA256', SIGNATURE_KEY, payload_body)

# Use secure_compare for timing-attack resistance
is_valid = ActiveSupport::SecurityUtils.secure_compare(provided_signature, expected_signature)

if is_valid
  # Signature is valid, process the webhook payload
  puts "Webhook signature verified."
else
  # Signature is invalid, reject the request
  puts "Webhook signature verification failed."
  # Return an appropriate error response (e.g., 401 Unauthorized)
end
```

### Delivery Attempts & Reliability

Our system will attempt to deliver webhook events to your configured endpoint.
If your endpoint returns a non-2xx status code (e.g., 4xx, 5xx) or fails to respond within a reasonable timeout, we will retry sending that event. We retry up to 25 times with exponential time backoff (e.g. after 15 seconds, 16 seconds, 30 seconds, 90 seconds, etc) for a total period of around 20 days.

It is crucial that your endpoint:

1. Responds quickly with a `200 OK` status upon successful receipt of the request (ideally before performing complex processing).
2. Is designed to handle potential duplicate events (e.g., due to network issues or retries).
3. Handles the signature verification process robustly.


## Profiles

Profiles represent a set of Personally Identifiable Information (PII) for a person who will be checked.
Profiles can be updated with the latest information for a person and be referenced to generate checks.

### Name validation

Checkr attempts to prevent malformed names (for example, `12345`) from being submitted. This applies
anywhere a name is accepted: `full_name`, `first_name`, `middle_name`, and `last_name`. A request that
contains a name determined to be malformed is rejected with `400 Bad Request` and a `validation_error`
whose `source.pointer` identifies the offending field (such as `/first_name`). No profile is created or
updated and no check is run.

## Driver Checks

Driver checks provide the resulting information relevant to the requested driver license.
The response will include the driver check type and results.

### Create a New Driver Check

Creates a new Driver Check, returning the results asynchronously, using a pre-defined webhook.

Required Fields

The required attributes for a driver check vary depending on its intended use.
You can pass through the minimum set of PII or a `profile_id` to reference the profile’s PII—not both.
Combining `profile_id` with inline PII or address fields returns `400 Bad Request`.
If the PII is insufficient for a driver check, a validation error will return a `400 Bad Request`.

Fields required to generate a `Driver Check` include:

- `first_name`
- `last_name`
- `dob`
- `driver_license_number`
- `driver_license_state`


### Parse Driver Check Results

Asynchronous responses for a Driver Check and GET requests for a Driver Check both contain the same information about the results.
You must expose a [Webhook endpoint](#webhooks) on your end to receive Driver Check completion events.
Configure this webhook URL in your product configuration settings, either in the dashboard under Configuration or with your Checkr Account Executive.
Additionally, Checkr does not make any policy decisions on behalf of its customers.