Quick Start with APIs

This guide walks you through creating your first background check using the Checkr API. You'll create a candidate, send an invitation, and retrieve the resulting report.

Prefer to use an AI assistant? Copy the prompt below into Claude, ChatGPT, Cursor, or whichever one you use. It'll ask for a few details, then take you through the steps below itself.

You are helping me run through the Checkr Quick Start guide.

## Your first task
Fetch and read the Quick Start page:
https://docs.checkr.com/get-started/quick-start.md

Use the steps described on that page as your execution plan. Steps 1, 2, and 4 are API calls — execute those. Step 3 (candidate completes the apply flow) isn't an API call; handle it as described below. Skip the webhook step at the end — it's a dashboard configuration step, not part of this walkthrough.

## Before you start, ask me for:
1. My Checkr staging API key
2. A candidate email address
3. The package slug to use — only ask if I mention I have a specific one configured; otherwise use the default package shown in the cURL example on the page

**Note:** If I don't have a staging API key yet, tell me to follow the steps at https://docs.checkr.com/get-started/prerequisites before proceeding.

## How to execute
- Work through each step in order
- Make the actual API call for each step
- Show me each step's full response as pretty-printed JSON. Do not pipe through `jq`, `python`, or any external tool — format it yourself in your reply. Format only — never change the values. If the body isn't valid JSON, show it raw.
- Extract and carry forward any IDs between steps automatically
- If a step fails, explain what went wrong and suggest a fix
- When you reach the step where the candidate completes the application: pause, display the invitation URL from the previous response, and tell me to open it in my browser and complete the apply flow as if I were the candidate. Wait for me to confirm I've completed it before continuing.
- When retrieving the report, if the status isn't `complete` yet, wait about 10 seconds and check again, up to 3 times, before telling me to check back later.

Ready? Fetch the page first, then ask me for the inputs.

1. 1

   Create a candidate

   A candidate is the individual being screened. Create one by providing their basic information.

   cURLPythonJavaScript

   const response = await fetch('https://api.checkr-staging.com/v1/candidates', {
       method: 'POST',
       headers: {
           'Authorization': 'Basic ' + btoa('YOUR_API_KEY:'),
           'Content-Type': 'application/x-www-form-urlencoded',
       },
       body: new URLSearchParams({
           first_name: 'John',
           last_name: 'Smith',
           email: 'john.smith@example.com',
           dob: '1990-01-01',
           ssn: 'XXX-XX-XXXX',
           zipcode: '90401',
           'work_location[country]': 'US',
       }),
   });
   const candidate = await response.json();
   console.log(candidate.id); // Save this for the next step

   Request fields

   emailstring, (email)required

   Candidate's email address.

   first_namestring

   Candidate's first name.

   last_namestring

   Candidate's last name.

   dobstring, (date)

   Date of birth in YYYY-MM-DD format.

   ssnstring

   Social Security Number. Required for most US screenings.

   zipcodestring^\d{5}$

   Candidate's 5-digit zip code.

   work_locationsArray of objects

   Array of work location objects. Required for non-US screenings.

   Response fields

   idstring

   The candidate ID. Save this — you'll use it in the next step.

   objectstring

   Always 'candidate'

   Value:"candidate"

   report_idsArray of strings

   Report IDs associated with this candidate. Empty until a check is ordered.

2. 2

   Create an invitation

   An invitation emails the candidate a link to complete their background check application. Specify the candidate_id from Step 1 and the package to run.

   cURLPythonJavaScript

   curl -u YOUR_API_KEY: \
     -X POST https://api.checkr-staging.com/v1/invitations \
     -d "candidate_id=CANDIDATE_ID" \
     -d "package=basic_package"

   Request fields

   candidate_idstringrequired

   ID of the candidate from Step 1.

   packagestringrequired

   Slug of the screening package to run (e.g. driver_pro, tasker_standard).

   work_locationsArray of objects

   Array of work location objects. Required for hierarchy-enabled accounts.

   tagsArray of strings

   Optional tags to apply to the resulting report.

   Response fields

   idstring

   The invitation ID.

   statusstring

   Current status: pending, completed, or expired.

   Enum:"pending""completed""expired"

   invitation_urlstring, (uri)

   The URL sent to the candidate to complete their application.

   report_idstring or null

   ID of the report created once the candidate completes the apply flow. null until then.

   expires_atstring, (date-time)

   Timestamp when the invitation expires.

3. 3

   Candidate completes the apply flow

   The invitation emails the candidate a link to Checkr’s hosted apply flow, where they confirm their information, provide consent, and submit their application. In staging, you can simulate this step using Checkr’s test tools — no real candidate interaction is required.

4. 4

   Retrieve the report

   Once the candidate completes their application and the screenings process, a report is created. Retrieve it using the report_id from the invitation response or via webhook.

   cURLPythonJavaScript

   curl -u YOUR_API_KEY: \
     https://api.checkr-staging.com/v1/reports/REPORT_ID

   Response fields

   idstring

   The report ID.

   statusstring

   Overall report status: pending, complete, suspended, dispute, or canceled.

   Enum:"pending""complete""suspended""dispute""canceled"

   resultstring or null

   Screening outcome: clear or consider. null while the report is pending.

   Enum:"clear""consider"null

   adjudicationstring

   Adjudication status: engaged, pre_adverse_action, or post_adverse_action.

   Enum:"engaged""pre_adverse_action""post_adverse_action"

   completed_atstring, (date-time)

   Timestamp when all screenings finished.

   candidate_idstring

   ID of the associated candidate.

5. 5

   Rather than polling for report status, configure a webhook endpoint to receive real-time updates when a report or screening status changes.

   1. Go to Dashboard → Developer → Webhooks
   2. Add your endpoint URL
   3. Select the events to subscribe to (e.g., report.completed)

   Checkr will POST to your endpoint when the report is ready.