Checkr Getting Started: Account Setup & First API Request (2026)

Getting started overview

Integrating with the Checkr API involves a series of steps designed to enable programmatic initiation and management of background checks. This guide provides a framework for new users to navigate account creation, API key generation, and the execution of an initial API request. Checkr offers a RESTful API, supporting standard HTTP methods and JSON payloads for communication, which aligns with common web service integration patterns documented by organizations like the World Wide Web Consortium on web standards.

The primary goal is to perform a background check for a candidate. This process typically involves creating a candidate profile, initiating a background check (referred to as a 'report') for that candidate, and then retrieving the report's status and results. Checkr provides a sandbox environment for testing integrations without incurring charges or affecting live data, which is standard practice for API providers to facilitate development, as seen with Stripe's API documentation for testing.

Before making live requests, it is recommended to familiarize yourself with the Checkr Developer Documentation and the API Reference.

Quick Reference Guide

Create an account and get keys

To begin using the Checkr API, a Checkr account is necessary. Checkr offers various plans, starting with the Essential plan at $29.99 per background check. There is no free tier available for API usage, although a demo can be requested.

1. Sign Up for a Checkr Account: Navigate to the Checkr signup page and complete the registration process. This typically involves providing company details and agreeing to terms of service.
2. Access the Dashboard: Once your account is created and verified, log in to the Checkr dashboard.
3. Locate API Keys: In the dashboard, find the section related to API access or Developer settings. This is usually under Account Settings or API. Checkr differentiates between sandbox keys for testing and production keys for live operations. For initial setup, use the sandbox keys. Your API keys will be displayed as a secret token.
4. Store Your API Key Securely: Your API key acts as a bearer token for authentication. It grants access to your Checkr account and should be treated with the same security considerations as passwords. Store it in environment variables or a secure configuration management system rather than hardcoding it directly into your application's source code.

Checkr's API keys are designed for authentication, adhering to common practices for securing API access. The Checkr authentication documentation provides further details on how to manage and use these keys.

Your first request

After obtaining your sandbox API key, you can make your first API call. This example demonstrates creating a candidate and then initiating a background check report for that candidate using curl. You can adapt these examples to your preferred SDK (Node.js, Ruby, Python, PHP, Java) by referring to the Checkr developer documentation.

Prerequisites

• Your Checkr sandbox API key.
• A command-line interface with curl installed.

Step 1: Create a Candidate

The first step in initiating a background check is to create a candidate. This involves providing basic identifying information for the individual being screened. Replace YOUR_SANDBOX_API_KEY with your actual sandbox API key.

curl -X POST \ 
  https://api.checkr.com/v1/candidates \ 
  -H 'Content-Type: application/json' \ 
  -H 'Authorization: Bearer YOUR_SANDBOX_API_KEY' \ 
  -d '{ 
    "first_name": "Jane", 
    "last_name": "Doe", 
    "email": "[email protected]", 
    "dob": "1990-01-01", 
    "ssn": "000-00-0000", 
    "zipcode": "94103" 
  }'

A successful response will return a JSON object containing the candidate's details, including a unique id. Make sure to note this id, as it will be used in the next step to initiate the background check.

{
  "id": "cand_YOUR_CANDIDATE_ID",
  "object": "candidate",
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "[email protected]",
  "dob": "1990-01-01",
  "ssn": "000-00-0000",
  "zipcode": "94103",
  "status": "clear"
  // ... other candidate details
}

Step 2: Initiate a Report for the Candidate

With the candidate id, you can now initiate a background check report. Checkr offers various report types (e.g., Essential, Professional, Executive) with different scopes. The following example uses the essential package. Replace YOUR_SANDBOX_API_KEY and YOUR_CANDIDATE_ID with your actual values.

curl -X POST \ 
  https://api.checkr.com/v1/reports \ 
  -H 'Content-Type: application/json' \ 
  -H 'Authorization: Bearer YOUR_SANDBOX_API_KEY' \ 
  -d '{ 
    "candidate_id": "YOUR_CANDIDATE_ID", 
    "package": "essential" 
  }'

A successful response will provide details about the initiated report, including its id and initial status, which will typically be pending.

{
  "id": "rep_YOUR_REPORT_ID",
  "object": "report",
  "candidate_id": "cand_YOUR_CANDIDATE_ID",
  "package": "essential",
  "status": "pending",
  "turnaround_time": null,
  "adjudication": null,
  "created_at": "2023-01-01T12:00:00Z"
  // ... other report details
}

Step 3: Retrieve Report Status (Optional but Recommended)

While webhooks are the best way to get real-time updates, you can also manually poll the report status. This is generally not recommended for production systems due to potential rate limiting and latency, but it can be useful for initial testing.

curl -X GET \ 
  https://api.checkr.com/v1/reports/rep_YOUR_REPORT_ID \ 
  -H 'Authorization: Bearer YOUR_SANDBOX_API_KEY'

The response will contain the current status of the report (e.g., pending, in_progress, complete). Once the status is complete, the full results will be available within the report object.

Common next steps

After successfully making your first API calls, consider these next steps to build out your Checkr integration:

• Implement Webhooks: Webhooks are critical for receiving real-time updates on report status changes without polling. Checkr sends HTTP POST requests to a specified URL when events occur (e.g., report completion). Configure your webhook endpoint in the Checkr dashboard under API > Webhooks and implement logic to process these notifications. This is a more efficient and scalable approach than repeatedly querying the API.
• Explore Different Report Packages: Checkr offers various background check packages with different scopes, such as Essential, Professional, and Executive. Understand the components of each package to select the one that best fits your hiring needs.
• Integrate with SDKs: While curl is useful for quick tests, using one of Checkr's official SDKs (Node.js, Ruby, Python, PHP, Java) can streamline development by providing language-specific constructs and handling authentication automatically. Refer to the SDK documentation for installation and usage instructions.
• Handle Error Responses: Implement robust error handling in your application. Checkr's API returns standard HTTP status codes (e.g., 4xx for client errors, 5xx for server errors) and detailed JSON error messages. Consult the error handling guide in the documentation.
• Transition to Production: Once your integration is thoroughly tested in the sandbox environment, switch to your production API keys and endpoints. Ensure all personal identifiable information (PII) is handled securely and in compliance with regulations like FCRA, GDPR, and CCPA.

Troubleshooting the first call

Encountering issues during your first API calls is common. Here are some troubleshooting tips for Checkr integrations:

• Incorrect API Key: Double-check that you are using the correct API key. Ensure you're using a sandbox key for sandbox endpoints and a production key for production endpoints. API keys are case-sensitive.
• Authentication Errors (401 Unauthorized): If you receive a 401 Unauthorized error, verify that your Authorization: Bearer YOUR_API_KEY header is correctly formatted and that the key itself is valid and not expired.
• Invalid Request Payload (400 Bad Request): This error indicates an issue with the JSON body of your request. Common causes include missing required fields (e.g., first_name, last_name for a candidate), incorrect data types, or malformed JSON. Refer to the API Reference for the exact schema required for each endpoint.
• Resource Not Found (404 Not Found): If you get a 404, you might be trying to access a resource (like a candidate or report) that doesn't exist, or you have a typo in the endpoint URL. Verify the ids you are using and the API endpoint path.
• Rate Limiting (429 Too Many Requests): Checkr, like many APIs, enforces rate limits to prevent abuse. If you hit this, reduce the frequency of your requests. The Checkr documentation on rate limits provides details on current limits and recommended handling strategies.
• Network Connectivity Issues: Ensure your development environment has stable internet access and no firewalls are blocking outgoing requests to api.checkr.com.
• Check Server Logs: If you are running a server-side application, review your application's logs for any errors generated before the API call or when processing the response.
• Consult Checkr Documentation: The Checkr Developer Documentation is the primary resource for detailed information on endpoints, request/response structures, and error codes.