{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition","accordion","numbered-list","numbered-item","code-group","json-schema","cards","card"]},"type":"markdown"},"seo":{"title":"Quick Start with APIs","description":"Checkr developer documentation for background check APIs, embeds, and partner integrations."},"dynamicMarkdocComponents":["openapi"],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"quick-start-with-apis","__idx":0},"children":["Quick Start with APIs"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Staging environment"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["All requests in this guide use the staging environment (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["api.checkr-staging.com"]},"). No real checks are run."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"success","name":"Before you begin"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Don't have a Checkr staging account and API key? Follow the steps on the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/get-started/prerequisites"},"children":["API Keys"]}," page first."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"run-with-ai","__idx":1},"children":["Run with AI"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Accordion","attributes":{"title":"Copy prompt","expanded":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"markdown","header":{"controls":{"copy":{}}},"source":"You are helping me run through the Checkr Quick Start guide.\n\n## Your first task\nFetch and read the Quick Start page:\nhttps://docs.checkr.com/get-started/quick-start.md\n\nUse 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.\n\n## Before you start, ask me for:\n1. My Checkr staging API key\n2. A candidate email address\n3. 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\n\n**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.\n\n## How to execute\n- Work through each step in order\n- Make the actual API call for each step\n- 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.\n- Extract and carry forward any IDs between steps automatically\n- If a step fails, explain what went wrong and suggest a fix\n- 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.\n- 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.\n\nReady? Fetch the page first, then ask me for the inputs.\n","lang":"markdown"},"children":[]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"steps","__idx":2},"children":["Steps"]},{"$$mdtype":"Tag","name":"NumberedList","attributes":{"type":"number","size":"medium"},"children":[{"$$mdtype":"Tag","name":"NumberedItem","attributes":{"headline":["Create a candidate"],"anchorId":"create-a-candidate","headlineLevel":3,"type":"number","size":"medium","index":1,"isLast":false},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A candidate is the individual being screened. Create one by providing their basic information."]},{"$$mdtype":"Tag","name":"CodeGroup","attributes":{"mode":"tabs"},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","data-title":"cURL","header":{"title":"cURL","controls":{"copy":{}}},"source":"const response = await fetch('https://api.checkr-staging.com/v1/candidates', {\n    method: 'POST',\n    headers: {\n        'Authorization': 'Basic ' + btoa('YOUR_API_KEY:'),\n        'Content-Type': 'application/x-www-form-urlencoded',\n    },\n    body: new URLSearchParams({\n        first_name: 'John',\n        last_name: 'Smith',\n        email: 'john.smith@example.com',\n        dob: '1990-01-01',\n        ssn: 'XXX-XX-XXXX',\n        zipcode: '90401',\n        'work_location[country]': 'US',\n    }),\n});\nconst candidate = await response.json();\nconsole.log(candidate.id); // Save this for the next step\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"python","header":{"controls":{"copy":{}}},"source":"import requests\n\nresponse = requests.post(\n    'https://api.checkr-staging.com/v1/candidates',\n    auth=('YOUR_API_KEY', ''),\n    data={\n        'first_name': 'John',\n        'last_name': 'Smith',\n        'email': 'john.smith@example.com',\n        'dob': '1990-01-01',\n        'ssn': 'XXX-XX-XXXX',\n        'zipcode': '90401',\n        'work_location[country]': 'US',\n    }\n)\ncandidate = response.json()\nprint(candidate['id'])  # Save this for the next step\n","lang":"python"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"const response = await fetch('https://api.checkr-staging.com/v1/candidates', {\n  method: 'POST',\n  headers: {\n    'Authorization': 'Basic ' + btoa('YOUR_API_KEY:'),\n    'Content-Type': 'application/x-www-form-urlencoded',\n  },\n  body: new URLSearchParams({\n    first_name: 'John',\n    last_name: 'Smith',\n    email: 'john.smith@example.com',\n    dob: '1990-01-01',\n    ssn: 'XXX-XX-XXXX',\n    zipcode: '90401',\n    'work_location[country]': 'US',\n  }),\n});\nconst candidate = await response.json();\nconsole.log(candidate.id); // Save this for the next step \n","lang":"javascript"},"children":[]}]},{"$$mdtype":"Tag","name":"Accordion","attributes":{"title":"Request fields","expanded":false},"children":[{"$$mdtype":"Tag","name":"JsonSchema","attributes":{"schema":{"title":"Candidate","type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email","description":"Candidate's email address."},"first_name":{"type":"string","description":"Candidate's first name."},"last_name":{"type":"string","description":"Candidate's last name."},"dob":{"type":"string","format":"date","description":"Date of birth in `YYYY-MM-DD` format."},"ssn":{"type":"string","description":"Social Security Number. Required for most US screenings."},"zipcode":{"type":"string","pattern":"^\\d{5}$","description":"Candidate's 5-digit zip code."},"work_locations":{"type":"array","description":"Array of work location objects. Required for non-US screenings.","items":{"type":"object"}}}},"options":{},"schemaResolved":{"openapi":"3.1.0","components":{"schemas":{"__root":{"title":"Candidate","type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email","description":"Candidate's email address."},"first_name":{"type":"string","description":"Candidate's first name."},"last_name":{"type":"string","description":"Candidate's last name."},"dob":{"type":"string","format":"date","description":"Date of birth in `YYYY-MM-DD` format."},"ssn":{"type":"string","description":"Social Security Number. Required for most US screenings."},"zipcode":{"type":"string","pattern":"^\\d{5}$","description":"Candidate's 5-digit zip code."},"work_locations":{"type":"array","description":"Array of work location objects. Required for non-US screenings.","items":{"type":"object"}}}}}}},"schemaResolvedErrors":[]},"children":[]}]},{"$$mdtype":"Tag","name":"Accordion","attributes":{"title":"Response fields","expanded":false},"children":[{"$$mdtype":"Tag","name":"JsonSchema","attributes":{"schema":{"title":"Candidate","type":"object","properties":{"id":{"type":"string","description":"The candidate ID. Save this — you'll use it in the next step."},"object":{"type":"string","const":"candidate","description":"Always 'candidate'"},"report_ids":{"type":"array","description":"Report IDs associated with this candidate. Empty until a check is ordered.","items":{"type":"string"}}}},"options":{},"schemaResolved":{"openapi":"3.1.0","components":{"schemas":{"__root":{"title":"Candidate","type":"object","properties":{"id":{"type":"string","description":"The candidate ID. Save this — you'll use it in the next step."},"object":{"type":"string","const":"candidate","description":"Always 'candidate'"},"report_ids":{"type":"array","description":"Report IDs associated with this candidate. Empty until a check is ordered.","items":{"type":"string"}}}}}}},"schemaResolvedErrors":[]},"children":[]}]}]},{"$$mdtype":"Tag","name":"NumberedItem","attributes":{"headline":["Create an invitation"],"anchorId":"create-an-invitation","headlineLevel":3,"type":"number","size":"medium","index":2,"isLast":false},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"CodeGroup","attributes":{"mode":"tabs"},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","data-title":"cURL","header":{"title":"cURL","controls":{"copy":{}}},"source":"curl -u YOUR_API_KEY: \\\n  -X POST https://api.checkr-staging.com/v1/invitations \\\n  -d \"candidate_id=CANDIDATE_ID\" \\\n  -d \"package=basic_package\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"python","data-title":"Python","header":{"title":"Python","controls":{"copy":{}}},"source":"import requests\n\nresponse = requests.post(\n    'https://api.checkr-staging.com/v1/invitations',\n    auth=('YOUR_API_KEY', ''),\n    data={\n        'candidate_id': 'CANDIDATE_ID',\n        'package': 'basic_package',\n    }\n)\ninvitation = response.json()\nprint(invitation['invitation_url'])  # Sent to the candidate\n","lang":"python"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","data-title":"JavaScript","header":{"title":"JavaScript","controls":{"copy":{}}},"source":"const response = await fetch('https://api.checkr-staging.com/v1/invitations', {\n  method: 'POST',\n  headers: {\n    'Authorization': 'Basic ' + btoa('YOUR_API_KEY:'),\n    'Content-Type': 'application/x-www-form-urlencoded',\n  },\n  body: new URLSearchParams({\n    candidate_id: 'CANDIDATE_ID',\n    package: 'basic_package',\n  }),\n});\nconst invitation = await response.json();\nconsole.log(invitation.invitation_url); // Sent to the candidate\n","lang":"javascript"},"children":[]}]},{"$$mdtype":"Tag","name":"Accordion","attributes":{"title":"Request fields","expanded":false},"children":[{"$$mdtype":"Tag","name":"JsonSchema","attributes":{"schema":{"title":"CreateReportRequest","type":"object","required":["candidate_id","package"],"properties":{"candidate_id":{"type":"string","description":"ID of the candidate from Step 1."},"package":{"type":"string","description":"Slug of the screening package to run (e.g. driver_pro, tasker_standard)."},"work_locations":{"type":"array","description":"Array of work location objects. Required for hierarchy-enabled accounts.","items":{"type":"object"}},"tags":{"type":"array","description":"Optional tags to apply to the resulting report.","items":{"type":"string"}}}},"options":{},"schemaResolved":{"openapi":"3.1.0","components":{"schemas":{"__root":{"title":"CreateReportRequest","type":"object","required":["candidate_id","package"],"properties":{"candidate_id":{"type":"string","description":"ID of the candidate from Step 1."},"package":{"type":"string","description":"Slug of the screening package to run (e.g. driver_pro, tasker_standard)."},"work_locations":{"type":"array","description":"Array of work location objects. Required for hierarchy-enabled accounts.","items":{"type":"object"}},"tags":{"type":"array","description":"Optional tags to apply to the resulting report.","items":{"type":"string"}}}}}}},"schemaResolvedErrors":[]},"children":[]}]},{"$$mdtype":"Tag","name":"Accordion","attributes":{"title":"Response fields","expanded":false},"children":[{"$$mdtype":"Tag","name":"JsonSchema","attributes":{"schema":{"title":"Invitation","type":"object","properties":{"id":{"type":"string","description":"The invitation ID."},"status":{"type":"string","enum":["pending","completed","expired"],"description":"Current status: pending, completed, or expired."},"invitation_url":{"type":"string","format":"uri","description":"The URL sent to the candidate to complete their application."},"report_id":{"type":["string","null"],"description":"ID of the report created once the candidate completes the apply flow. null until then."},"expires_at":{"type":"string","format":"date-time","description":"Timestamp when the invitation expires."}}},"options":{},"schemaResolved":{"openapi":"3.1.0","components":{"schemas":{"__root":{"title":"Invitation","type":"object","properties":{"id":{"type":"string","description":"The invitation ID."},"status":{"type":"string","enum":["pending","completed","expired"],"description":"Current status: pending, completed, or expired."},"invitation_url":{"type":"string","format":"uri","description":"The URL sent to the candidate to complete their application."},"report_id":{"type":["string","null"],"description":"ID of the report created once the candidate completes the apply flow. null until then."},"expires_at":{"type":"string","format":"date-time","description":"Timestamp when the invitation expires."}}}}}},"schemaResolvedErrors":[]},"children":[]}]}]},{"$$mdtype":"Tag","name":"NumberedItem","attributes":{"headline":["Candidate completes the apply flow"],"anchorId":"candidate-completes-the-apply-flow","headlineLevel":3,"type":"number","size":"medium","index":3,"isLast":false},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]}]},{"$$mdtype":"Tag","name":"NumberedItem","attributes":{"headline":["Retrieve the report"],"anchorId":"retrieve-the-report","headlineLevel":3,"type":"number","size":"medium","index":4,"isLast":false},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Once the candidate completes their application and the screenings process, a report is created. Retrieve it using the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["report_id"]}," from the invitation response or via webhook."]},{"$$mdtype":"Tag","name":"CodeGroup","attributes":{"mode":"tabs"},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","data-title":"cURL","header":{"title":"cURL","controls":{"copy":{}}},"source":"curl -u YOUR_API_KEY: \\\n  https://api.checkr-staging.com/v1/reports/REPORT_ID\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"python","data-title":"Python","header":{"title":"Python","controls":{"copy":{}}},"source":"import requests\n\nresponse = requests.get(\n    'https://api.checkr-staging.com/v1/reports/REPORT_ID',\n    auth=('YOUR_API_KEY', '')\n)\nreport = response.json()\nprint(report['status'])  # pending, complete, suspended, etc.\nprint(report['result'])  # clear or consider\n","lang":"python"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","data-title":"JavaScript","header":{"title":"JavaScript","controls":{"copy":{}}},"source":"const response = await fetch('https://api.checkr-staging.com/v1/reports/REPORT_ID', {\n  headers: {\n    'Authorization': 'Basic ' + btoa('YOUR_API_KEY:'),\n  },\n});\nconst report = await response.json();\nconsole.log(report.status); // pending, complete, suspended, etc.\nconsole.log(report.result); // clear or consider\n","lang":"javascript"},"children":[]}]},{"$$mdtype":"Tag","name":"Accordion","attributes":{"title":"Response fields","expanded":false},"children":[{"$$mdtype":"Tag","name":"JsonSchema","attributes":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"Report","type":"object","properties":{"id":{"type":"string","description":"The report ID."},"status":{"type":"string","enum":["pending","complete","suspended","dispute","canceled"],"description":"Overall report status: pending, complete, suspended, dispute, or canceled."},"result":{"type":["string","null"],"enum":["clear","consider",null],"description":"Screening outcome: clear or consider. null while the report is pending."},"adjudication":{"type":"string","enum":["engaged","pre_adverse_action","post_adverse_action"],"description":"Adjudication status: engaged, pre_adverse_action, or post_adverse_action."},"completed_at":{"type":"string","format":"date-time","description":"Timestamp when all screenings finished."},"candidate_id":{"type":"string","description":"ID of the associated candidate."}}},"options":{},"schemaResolved":{"openapi":"3.1.0","components":{"schemas":{"__root":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"Report","type":"object","properties":{"id":{"type":"string","description":"The report ID."},"status":{"type":"string","enum":["pending","complete","suspended","dispute","canceled"],"description":"Overall report status: pending, complete, suspended, dispute, or canceled."},"result":{"type":["string","null"],"enum":["clear","consider",null],"description":"Screening outcome: clear or consider. null while the report is pending."},"adjudication":{"type":"string","enum":["engaged","pre_adverse_action","post_adverse_action"],"description":"Adjudication status: engaged, pre_adverse_action, or post_adverse_action."},"completed_at":{"type":"string","format":"date-time","description":"Timestamp when all screenings finished."},"candidate_id":{"type":"string","description":"ID of the associated candidate."}}}}}},"schemaResolvedErrors":[]},"children":[]}]}]},{"$$mdtype":"Tag","name":"NumberedItem","attributes":{"type":"number","size":"medium","index":5,"isLast":true},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Rather than polling for report status, configure a webhook endpoint to receive real-time updates when a report or screening status changes."]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Go to ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Dashboard → Developer → Webhooks"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Add your endpoint URL"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Select the events to subscribe to (e.g., ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["report.completed"]},")"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Checkr will POST to your endpoint when the report is ready."]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"next-steps","__idx":3},"children":["Next steps"]},{"$$mdtype":"Tag","name":"Cards","attributes":{"columns":2,"cardMinWidth":240},"children":[{"$$mdtype":"Tag","name":"Card","attributes":{"title":"Webhooks","icon":"solid bell","imagePosition":"start","iconPosition":"auto","layout":"vertical","align":"start","variant":"filled","iconVariant":"ghost","to":"/apis/webhooks"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Go deeper on real-time events — payloads, security, and the full event catalog."]}]},{"$$mdtype":"Tag","name":"Card","attributes":{"title":"API Reference","icon":"solid book","imagePosition":"start","iconPosition":"auto","layout":"vertical","align":"start","variant":"filled","iconVariant":"ghost","to":"/apis/openapi"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Full API reference for candidates, reports, and webhooks."]}]}]}]},"headings":[{"value":"Quick Start with APIs","id":"quick-start-with-apis","depth":1},{"value":"Run with AI","id":"run-with-ai","depth":2},{"value":"Steps","id":"steps","depth":2},{"value":"Create a candidate","id":"create-a-candidate","depth":3},{"value":"Create an invitation","id":"create-an-invitation","depth":3},{"value":"Candidate completes the apply flow","id":"candidate-completes-the-apply-flow","depth":3},{"value":"Retrieve the report","id":"retrieve-the-report","depth":3},{"value":"Next steps","id":"next-steps","depth":2}],"frontmatter":{"title":"Quick Start with APIs","description":"Create your first background check in under 15 minutes.","seo":{"title":"Quick Start with APIs"}},"lastModified":"2026-11-11T18:56:04.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/get-started/quick-start","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}