{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-apis/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition","numbered-list","numbered-item","img"]},"type":"markdown"},"seo":{"title":"Getting Started","description":"Checkr developer documentation for background check APIs, embeds, and partner integrations."},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"getting-started","__idx":0},"children":["Getting Started"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following sections will walk you through the steps necessary to get started running background checks with the Checkr API."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Please reach out to ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"mailto:clients@checkr.com"},"children":["clients@checkr.com"]}," before you start integrating with our API to learn about our approval process for production."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"get-credentialed","__idx":1},"children":["Get credentialed"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Before gaining access to the Checkr APIs and Dashboard, you must be properly credentialed to request background checks. Work with your Customer Support Representative to provide the required documentation, and complete the credentialing process."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For more information, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/introduction#get-credentialed"},"children":["Getting credentialed"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"request-a-staging-account","__idx":2},"children":["Request a staging account"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Checkr provides customers with the option of a \"staging account\" that can be used to test your integration and use the Checkr Dashboard prior to deploying your integration to your production account. The staging account can be set up to match the settings from your production account and allows for submission of background check orders without incurring any billable events. To accomplish this, Checkr uses candidate \"mocked\" data setups that result in predefined background check results, mimicking the most common outcomes you will encounter in your production account."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Once your staging account has been created, Checkr will provide you with a document containing this mocked candidate data."]},{"$$mdtype":"Tag","name":"NumberedList","attributes":{"type":"number","size":"medium"},"children":[{"$$mdtype":"Tag","name":"NumberedItem","attributes":{"type":"number","size":"medium","index":1,"isLast":false},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Submit a staging account request"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use our Help Center ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://help.checkr.com/helpcenter/s/article/23292336791447-FAQs-about-Checkr-s-API"},"children":["article"]}," to guide you through the request to create a staging account."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Staging accounts can only be created using a production account that has already been authenticated."]}]}]},{"$$mdtype":"Tag","name":"NumberedItem","attributes":{"type":"number","size":"medium","index":2,"isLast":true},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Configure your staging account"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Upon successful creation of the staging account, the email address specified in the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://help.checkr.com/hc/en-us/requests/new?ticket_form_id=360004180714"},"children":["staging account request submission"]}," will receive an email from Checkr providing a temporary password to the account and allowing the recipient to create a permanent password. This initial user will have an Admin user role which allows them to invite other users to the account as they see fit."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Once you have Admin access to the staging account, go to ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Account Settings > Developer Settings"]},". On this page, in the \"API keys\" section click ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Create Key"]}," and choose ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Secret"]},". Use the resulting API key to authenticate all of your API calls to this staging account."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To enable webhooks for the account, from the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Account Settings > Developer Settings"]}," page scroll down to ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["New Webhook"]},". Enter a URL and click ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Add"]}," to create a new webhook. You may also use this page to select the webhook notifications you wish to receive from Checkr."]},{"$$mdtype":"Tag","name":"Image","attributes":{"src":"/assets/accountsettingsdeveloperswebhooks.034cd7a9cc820afb21408ff307c5a3af517918c62e2832c4bd73326cbe35bb6f.9c1bb791.png","alt":"Webhooks configuration","framed":false,"withLightbox":false},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The staging account's API calls, responses, and webhooks follow the same pattern and response structure as those of the production environment."]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The staging account uses the API host URL: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://api.checkr-staging.com/v1"]}," for all calls."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"testing-checkrs-functions-and-features","__idx":3},"children":["Testing Checkr's functions and features"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To facilitate building with the Checkr API, Checkr staging accounts support a number of mocked candidate profiles that will return predictable results. This allows you to test a number of different report outcomes and other workflows before moving your integration to your production account. To ensure the desired outcome, you must enter the candidate data exactly as provided in this mocked candidate data document or the resulting report will remain in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pending"]}," status indefinitely."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Reports created in the staging account will typically complete within minutes of submission, though this can vary depending upon the relative load on the staging environment servers."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Checkr's product and development teams also use the staging environment to test new functionality. It is therefore possible that one or more of the mocked candidate records may not return the expected results. If you encounter unexpected returns for a mock data candidate, please test a different candidate from the mocked data document with a similar predefined outcome. If the problem persists, reach out to your Checkr Customer Support Manager to troubleshoot the issue."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"uses-and-limitations-of-the-staging-account","__idx":4},"children":["Uses and limitations of the staging account"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The staging account is built to mimic the production environment and allow developers to build without running production background screenings and incurring a charge. Staging account uses mocked candidate data, and does not support the following functionality available in the production environment:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Post adverse action is not supported"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Invitations do not expire"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Invoices are not created"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Analytics are not available"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Please reach out to your Checkr Account Executive or Customer Success Manager if you require additional status, report, or state test cases."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"get-your-api-key","__idx":5},"children":["Get your API key"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Once you have access set up to log into Checkr, go to ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://dashboard.checkr.com/account/developer_settings"},"children":["Developer Settings"]}," in the Checkr Dashboard. Click ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Create Key > Secret"]}," to generate a new Secret Key for your staging environment."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Your production API key is also available from this ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://dashboard.checkr.com/account/developer_settings"},"children":["Developer Settings"]}," page. Note that your production key will not be enabled for Reports until you contact clients@checkr.com and request that your account be enabled for live requests."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For more information on using Checkr's Staging environment, see the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#request-a-staging-account"},"children":["Requesting a Staging Account"]}," section."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"set-up-a-local-api-client","__idx":6},"children":["Set up a local API client"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Checkr provides support for several API clients, allowing you to explore the Checkr APIs. Download and install ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://www.postman.com/downloads/"},"children":["Postman"]}," or ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://docs.insomnia.rest/"},"children":["Insomnia"]},", then click the buttons below to install the Checkr APIs. Or use our ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://api.redocly.com/registry/bundle/checkr/Checkr%20Public%20API/v1/openapi.yaml"},"children":["OAS3 API spec"]}," to work with the tooling of your choice."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://god.gw.postman.com/run-collection/17709267-82bc3552-fc3c-4cf0-a11a-071ba6beb5bd?action=collection%2Ffork&collection-url=entityId%3D17709267-82bc3552-fc3c-4cf0-a11a-071ba6beb5bd%26entityType%3Dcollection%26workspaceId%3D46c6cc7f-9630-4414-bd15-0b2cfc79b7b9"},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"https://run.pstmn.io/button.svg","alt":"Run in Postman"},"children":[]}]}," ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://insomnia.rest/run/?label=Checkr&uri=https%3A%2F%2Fapi.redocly.com%2Fregistry%2Fbundle%2Fcheckr%2FCheckr%2520Public%2520API%2Fv1%2Fopenapi.yaml"},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"https://insomnia.rest/images/run.svg","alt":"Run in Insomnia}"},"children":[]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"configure-your-api-client","__idx":7},"children":["Configure your API client"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Configure your API client using the API key from the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://dashboard.checkr.com/account/developer_settings"},"children":["Developer Settings"]}," page in your Checkr Dashboard. Then use your local client to execute any Checkr API requests. We provide sample parameters and payloads throughout these developer guides to help you in your journey."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Checkr APIs are updated frequently. Use your selected method to reimport our APIs to evaluate our most recent versions."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Checkr API host URLs:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Production: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://api.checkr.com/v1"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Staging (if you have been given access): ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://api.checkr-staging.com/v1"]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"authenticate-with-checkr","__idx":8},"children":["Authenticate with Checkr"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use HTTP Basic authentication to authenticate with Checkr, with your API key as the username and an empty password. When using ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["curl"]},", use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["-u"]}," option to specify your API key. (Note the colon following the API key in the examples. It tells cURL to send an empty password.)"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl https://api.checkr.com \\\n  -u YOUR_SECRET_API_KEY:\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Note that staging environment requests are free and return fake data. Once you are production-ready, please email clients@checkr.com and we will enable live requests."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"create-a-candidate","__idx":9},"children":["Create a candidate"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Create a Candidate by passing the required PII to Checkr."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST https://api.checkr.com/v1/candidates \\\n  -u YOUR_API_KEY: \\\n  -d first_name=Michael \\\n  -d middle_name=Gary \\\n  -d last_name=Scott \\\n  -d email=michael.scott@dundermifflin.com \\\n  -d phone=2035408926 \\\n  -d zipcode=06831 \\\n  -d dob=1964-03-15 \\\n  -d ssn=111-11-2001 \\\n  -d driver_license_number=981736076 \\\n  -d driver_license_state=CT \\\n  -d copy_requested=true \\\n  -d 'work_locations[][country]=US'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Remember to replace ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["YOUR_SECRET_API_KEY"]}," with ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["your"]}," Secret API key. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/openapi/candidates"},"children":["Candidates"]}," for more details on creating Candidates."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Notes:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The Candidate object represents the candidate to be screened."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["copy_requested"]}," boolean captures whether or not the candidate has requested a copy of their background check upon completion. If ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]},", Checkr will automatically send a copy of the background check to the passed email address on your behalf."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If using a ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/introduction#checkr-hosted-candidate-experience"},"children":["Checkr-hosted candidate experience"]},", the only strictly required parameter for creating a Candidate in Checkr is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["email"]},". We recommend that the candidate's phone number also be provided when creating the Candidate object, as it will be required to authenticate the candidate when they log into the Candidate Portal."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If using a ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/introduction#self-hosted-candidate-experience"},"children":["custom self-hosted flow"]},", the required attributes include ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["first_name"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["middle_name"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["no_middle_name"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["last_name"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["dob"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If the Report's package includes any criminal check, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ssn"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["zipcode"]}," are required attributes."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If requesting a Motor Vehicle Report, Checkr requires ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["driver_license_number"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["driver_license_state"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Other Candidate-specific parameters are defined in the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/openapi/candidates/createcandidate"},"children":["Candidate resource"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"candidate-creation-response","__idx":10},"children":["Candidate creation response"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"id\":\"551564b7865af96a28b13f36\",\n  \"object\":\"candidate\",\n  \"uri\":\"/v1/candidates/551564b7865af96a28b13f36\",\n  \"created_at\":\"2018-08-17T01:08:18Z\",\n  \"first_name\":\"Michael\",\n  \"last_name\":\"Scott\",\n  \"middle_name\":\"Gary\",\n  \"mother_maiden_name\":null,\n  \"dob\":\"1964-03-15\",\n  \"ssn\":\"XXX-XX-2001\",\n  \"email\":\"michael.scott@dundermifflin.com\",\n  \"zipcode\":\"06831\",\n  \"phone\":\"2035408926\",\n  \"driver_license_state\":\"CT\",\n  \"driver_license_number\":\"981736076\",\n  \"copy_requested\":true,\n  \"previous_driver_license_state\":null,\n  \"previous_driver_license_number\":null,\n  \"adjudication\":null,\n  \"custom_id\":null,\n  \"no_middle_name\":false,\n  \"report_ids\":[],\n  \"geo_ids\":[]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Checkr responds immediately with the resulting Candidate object, which includes the ID of the Candidate and a URI that points to the new Candidate object. Store the ID for this new Candidate object, which you'll need when creating a Report in the next step."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"create-an-invitation","__idx":11},"children":["Create an invitation"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/openapi/invitations"},"children":["Invitations"]}," resource to order a background check using the Checkr-Hosted Apply Flow. Checkr will send an email to the candidate, inviting them to provide their information and consent. Once the invitation is completed a Report is automatically created. The invitation is valid for 7 days, during which Checkr will send a follow-up notice every 24 hours, reminding the candidate to complete their invitation. If 7 days pass and the candidate has not yet completed the invitation, the invitation will expire and you must create a new invitation to proceed with the candidate."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST https://api.checkr.com/v1/invitations \\\n  -u YOUR_API_KEY: \\\n  -d candidate_id=551564b7865af96a28b13f36 \\\n  -d package=dunder_mifflin_executive \\\n  -d work_locations[][state]=CA \\\n  -d work_locations[][city]=San+Francisco\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Parameters required to ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/openapi/invitations/createinvitation"},"children":["Create an invitation"]},":"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["candidate_id"]},": the ID of the candidate for whom the Invitation is created."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["package"]},": the Package to use for the background check."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["work_locations"]},": the candidate's work location, described using country, state, and city. (ISO-3166 alpha-2 format country code, two letter state code, and the name of the city)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["node"]}," (optional): the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["custom_id"]}," of the node associated with the background check. Required if any nodes exist on the account."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["work_location"]}," parameter is used by Checkr to determine compliance requirements for background check reports ordered through the Checkr Hosted Apply Flow. Checkr uses the candidate work location to apply the appropriate state- and city-based fair hiring laws, disclosures, and adverse action procedures. If a city is not provided, Checkr uses the state-based regulation."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"invitation-creation-response","__idx":12},"children":["Invitation creation response"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n    \"id\": \"551564b7865af96a28b13f36\",\n    \"object\": \"invitation\",\n    \"uri\": \"/v1/invitations/551564b7865af96a28b13f36\",\n    \"invitation_url\":\n\"https://apply.checkr.com/invite/try-checkr/290f9d6d6e46/test\",\n    \"status\": \"pending\",\n    \"created_at\": \"2015-05-14T17:45:34Z\",\n    \"expires_at\": \"2015-05-21T17:45:34Z\",\n    \"completed_at\": null,\n    \"deleted_at\": null,\n    \"package\": \"dunder_mifflin_executive\",\n    \"candidate_id\": \"551564b7865af96a28b13f36\",\n    \"report_id\": null\n    \"tags\": []\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the Checkr Candidate ID you have retrieved from ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#create-a-candidate"},"children":["Create a Candidate"]},", the Package \"slug\" (as selected in step ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/openapi/packages"},"children":["Selecting Packages"]},"), and the candidate's work location to create an Invitation."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Checkr requires Candidates to provide only information that is required for the screenings contained in the Package (such as SSN for criminal screenings, driver license number and state for MVR)."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Store the resulting Report ID and any of the requested Screening IDs. The ID for this new Report object is required to retrieve the Report. (Checkr will return IDs for all Screenings included in the requested Package. All other Screening IDs will be returned ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]},".)"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"listen-for-webhooks","__idx":13},"children":["Listen for webhooks"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If webhooks are enabled, Checkr pushes a status change webhook event to the customer account's webhook URL with the structure shown below."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"id\": \"507f1f77bcf86cd799439011\",\n  \"object\": \"event\",\n  \"type\": \"report.completed\",\n  \"created_at\": \"2014-01-18T12:34:00Z\",\n  \"data\": {\n    \"object\": {\n      \"id\": \"4722c07dd9a10c3985ae432a\",\n      \"object\": \"report\",\n      \"uri\": \"/v1/reports/532e71cfe88a1d4e8d00000d\",\n      \"created_at\": \"2014-01-18T12:34:00Z\",\n      \"received_at\": \"2014-01-18T12:34:00Z\",\n      \"status\": \"complete\",\n      \"result\": \"clear\",\n      \"package\": \"driver_pro\",\n      \"source\": \"api\",\n      \"candidate_id\": \"e44aa283528e6fde7d542194\",\n      \"ssn_trace_id\": \"539fd88c101897f7cd000001\",\n      \"sex_offender_search_id\": \"539fd88c101897f7cd000008\",\n      \"national_criminal_search_id\": \"539fd88c101897f7cd000006\",\n      \"county_criminal_search_ids\": [\n        \"539fdcf335644a0ef4000001\",\n        \"532e71cfe88a1d4e8d00000c\"\n      ],\n      \"state_criminal_search_ids\": [\n        \"539fdcf335644a0ef4000003\",\n        \"532e71cfe88a1d4e8d000004\"\n      ],\n      \"motor_vehicle_report_id\": \"539fd88c101897f7cd000007\"\n    }\n  },\n  \"account_id\": \"8e122cc56b8fa82d33c6118a\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the resulting Report status (or other data elements) to execute subsequent workflows in your application or program."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Subscribing to webhooks is the recommended approach for accessing the report information and status, since it provides near real-time updates and frees the customer from having to poll our API for this information."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"retrieve-a-report","__idx":14},"children":["Retrieve a report"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["While Checkr recommends listening to the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["report.completed"]}," webhook to retrieve the results of a report, you can also retrieve the same information by performing a GET request to the specific URL of the report."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Retrieve the Report created in the previous step by using your Secret API key and Report ID in the cURL command shown below."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X GET https://api.checkr.com/v1/reports/a13f4827d8711ddc75abc56ct \\\n  -u YOUR_API_KEY:\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"retrieve-report-response","__idx":15},"children":["Retrieve Report response"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"id\": \"a13f4827d8711ddc75abc56ct\",\n  \"object\": \"report\",\n  \"uri\": \"/v1/reports/a13f4827d8711ddc75abc56ct\",\n  \"status\": \"complete\",\n  \"result\": \"clear\",\n  \"created_at\": \"2018-08-17T01:10:21Z\",\n  \"completed_at\": \"2018-08-17T01:12:26Z\",\n  \"revised_at\": null,\n  \"upgraded_at\": null,\n  \"turnaround_time\": 52,\n  \"package\": \"dunder_mifflin_executive\",\n  \"tags\": [],\n  \"adjudication\": null,\n  \"assessment\": null,\n  \"source\": \"api\",\n  \"candidate_id\": \"551564b7865af96a28b13f36\",\n  \"county_criminal_search_ids\": [],\n  \"municipal_criminal_search_ids\": [],\n  \"document_ids\": [],\n  \"drug_alcohol_clearinghouse_id\": \"5b64c62b67abb4002d3ec763\",\n  \"federal_criminal_search_id\": \"5b64c62b67abb4002d3ec763\",\n  \"global_watchlist_search_id\": \"5b64c5cf67abb400353ec6f7\",\n  \"national_criminal_search_id\": \"5b64c5cf67abb400353ec6f5\",\n  \"personal_reference_verification_ids\": [],\n  \"professional_reference_verification_ids\": [],\n  \"sex_offender_search_id\": \"5b64c5cf67abb400353ec6f6\",\n  \"ssn_trace_id\": \"5b64c5cf67abb400353ec6f3\",\n  \"state_criminal_search_ids\": [],\n  \"terrorist_watchlist_search_id\": \"5b64c5cf67abb400353ec6f7\",\n  \"facis_search_id\": null,\n  \"arrest_search_id\": null,\n  \"motor_vehicle_report_id\": null,\n  \"self_disclosure_ids\": []\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Note that the Report is now a full Report with a status of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["clear"]},", indicating that no violations or criminal background have come up for this Report."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/reference#embedding-resources"},"children":["Embedding resources"]}," if you wish to embed the full contents of individual screenings (SSN Trace, Sex Offender Registry Search, Global Watchlist Search) in the server response. You can also retrieve those resources using the IDs provided in the server response."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"parse-the-results","__idx":16},"children":["Parse the results"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Webhook responses and completed Reports both contain the same information about the results of a criminal screening: the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}," of the report which can be ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["complete"]},", the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["result"]}," of the report which can be ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["clear"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["consider"]},", and the assessment of the report, which can be ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["eligible"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["review"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["escalated"]},"."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Values"},"children":["Values"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Meaning"},"children":["Meaning"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pending"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["complete"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["suspended"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paused"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["dispute"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["canceled"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Status of the report. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["canceled"]}," if and only if all screenings, including SSN Trace, within the report were canceled. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["complete"]}," if at least one screening was completed. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paused"]}," if the report is awaiting a Review Action decision to continue or skip."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["result"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["clear"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["consider"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Overall screening outcome"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["assessment"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["eligible"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["review"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["escalated"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Assess result (if enabled)"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A completed report with result of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["clear"]}," can be interpreted as that report having no items listed on the candidate's record that must be reviewed. A result of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["consider"]}," indicates that there are items on the candidate's record that may require consideration."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A report contains an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["assessment"]}," if the account has Assess enabled. The assessment is returned as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["eligible"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["review"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["escalated"]},", according to the customer rules defined in Assess. For more information, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://help.checkr.com/hc/en-us/articles/360051026954-Assess"},"children":["Assess"]}," in the Checkr User Guides."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In maintaining a compliant process as per FCRA legislation and EEOC guidelines, Checkr does not make any eligibility or hiring decisions (adjudicate) on our customers' behalf."]}]},"headings":[{"value":"Getting Started","id":"getting-started","depth":1},{"value":"Get credentialed","id":"get-credentialed","depth":2},{"value":"Request a staging account","id":"request-a-staging-account","depth":2},{"value":"Testing Checkr's functions and features","id":"testing-checkrs-functions-and-features","depth":3},{"value":"Uses and limitations of the staging account","id":"uses-and-limitations-of-the-staging-account","depth":3},{"value":"Get your API key","id":"get-your-api-key","depth":2},{"value":"Set up a local API client","id":"set-up-a-local-api-client","depth":2},{"value":"Configure your API client","id":"configure-your-api-client","depth":3},{"value":"Authenticate with Checkr","id":"authenticate-with-checkr","depth":2},{"value":"Create a candidate","id":"create-a-candidate","depth":2},{"value":"Candidate creation response","id":"candidate-creation-response","depth":3},{"value":"Create an invitation","id":"create-an-invitation","depth":2},{"value":"Invitation creation response","id":"invitation-creation-response","depth":3},{"value":"Listen for webhooks","id":"listen-for-webhooks","depth":2},{"value":"Retrieve a report","id":"retrieve-a-report","depth":2},{"value":"Retrieve Report response","id":"retrieve-report-response","depth":3},{"value":"Parse the results","id":"parse-the-results","depth":2}],"frontmatter":{"title":"Getting Started","description":"Get credentialed, set up staging, authenticate, and run your first background check.","seo":{"title":"Getting Started"}},"lastModified":"2026-09-18T05:44:09.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/apis/getting-started","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}