# Getting Started This Getting Started guide will walk you through enabling your Checkr application, and allowing your customers to connect to it. Please see the [Checkr API documentation](https://docs.checkr.com/#) for more information on our available APIs. If you are new to the regulatory aspects of background screenings, please see the [Checkr Help Center](https://help.checkr.com/hc/en-us)’s sections on [Compliance](https://help.checkr.com/hc/en-us/sections/203637107-Compliance), [Adjudication and Review](https://help.checkr.com/hc/en-us/sections/360000081367-Adjudication-and-Review), and Checkr [Screening Types](https://help.checkr.com/hc/en-us/sections/203637147-Screening-Types). For more information for your customers, including [Checkr Dashboard User Guides](https://help.checkr.com/hc/en-us/sections/360002119753-Checkr-Dashboard-User-Guide), [Getting Started with Checkr](https://help.checkr.com/hc/en-us/sections/203794077-Getting-Started), and the background check process, see the User Guides in our Help Center. ## Staging vs Production accounts As a partner of Checkr, you will be provided with both a Staging (test) account and a Production account. The Staging account is intended for your use when testing your partner integration with Checkr, while the Production account is for live, production use with your customers. The concepts and integration guidance provided in this document apply equally to both environments but there are a few key differences: * **API Base URL:** Staging uses https://api.checkr-staging.com/ while Production uses https://api.checkr.com/ * **Checkr Dashboard URL:** Staging uses https://dashboard.checkrhq-staging.net/ while Production uses https://dashboard.checkr.com/ ## Create a Partner Application for your Checkr account The first step to building a Checkr Partner integration is to set up your Checkr account with a "Partner Application". Partner Applications allow you to connect your customers’ Checkr accounts to yours. ![Create New Partner Application index](/assets/createnewpartnerappindex.eed302ac74dadc5246515a906d1dd1aa4a23486444fd85131bd5074cff44be56.9c1bb791.png) Create a New Partner Application from the Partner Dashboard at **Management > Applications > Add**. To create this Partner Application, enter the following information: * **Application name:** Your application’s name or brand. This name will be displayed in the Connect to Checkr flow. * **Application/Homepage URL:** Your website URL. This will be used on our Partners page on the Checkr corporate site. * **Application description:** A short description of your application. This will be used in Checkr Marketplace listings. * **Webhook URL:** An endpoint to which webhooks will be transmitted. This endpoint will receive all webhook events transmitted for your connected customer accounts. * **Redirect URL:** A page in your application to which your customers will be redirected after connecting their Checkr account using the Connect to Checkr flow. This URL must be HTTPS. It is used to secure your customers’ authentication and prevent Cross Site Request Forgery (CSRF) attacks. * **Logo:** Your logo which is used in the Connect-to-Checkr flow. * **Your company color:** The color you want to represent your brand. ![Create New Partner Application modal](/assets/createnewpartnerappmodal.3b8b13205781d94b0be80e41d6e2ccd3dd676649f8277c6811b16b34cd4f191b.9c1bb791.png) Once you’ve created your Partner Application, Checkr will generate a `client_id` and a `client_secret` to use as your application credentials. These credentials allow you to generate an OAuth token in order to make API calls on behalf of connected customers. Keep them safe! (Particularly your `client_secret`: this is a secret key that should be stored securely in your application and not shared with anyone.) ## Account Hierarchy Checkr customers often rely on Account Hierarchy for their workflows. Customers use their hierarchy to segment users' access, simplify selection of Packages at the time of order, and provide more granular detail on their monthly invoice. When building your partner integration, use the Nodes resource to check whether your customers have defined an Account Hierarchy. This will future-proof your integration and ensure that all of your customers, both those who do and those who do not use Account Hierarchies, can use the same codebase. ##### Retrieve a customer's Account Hierarchy ```sh $ curl -X GET /v1/nodes?page=1&per_page=25 -u {access_token} ``` ##### Example response when Account Hierarchy is not enabled ```json { "error": "Sorry, your account is not enabled for segmentation" } ``` ##### Example response when Account Hierarchy is enabled but no nodes exist ```json { "data": [], "object": "list", "next_href": null, "previous_href": null, "count": 0 } ``` ##### Example response when Account Hierarchy is enabled and nodes are defined ```json { "data": [ { "custom_id": "ROOT_74407af0533e", "name": "Root", "tier": "Company", "parent_custom_id": null }, { "custom_id": "CHLD_e7c3ab7bf4ad", "name": "Child 1", "tier": "Department", "parent_custom_id": "ROOT_74407af0533e", }, { "custom_id": "CHLD_a106e1bfcfd2", "name": "Child 2", "tier": "Department", "parent_custom_id": "ROOT_74407af0533e", } ], "object": "list", "next_href": null, "previous_href": null, "count": 3 } ``` If no hierarchy exists (the error message "Sorry, your account is not enabled for segmentation" is returned) or an empty result is returned leave the `node` parameter blank for that customer when creating candidate invitations. If a hierarchy is returned, a valid `custom_id` from the hierarchy results must be provided (as `node`) for invitations. Checkr provides several parameters on the GET /nodes endpoint to help you create a simple UI for selection (recommended) or to help automate the process without customer intervention (advanced). Your customer's `access_token` **must** be used in the request. See [Retrieve an access token](#retrieve-an-access-token) for information on how to obtain a customer's `access_token`. ## Connect your customers to Checkr The [Checkr-Hosted Signup flow](#use-the-checkr-hosted-signup-flow) automates account creation by collecting the information required to create Checkr accounts directly from your customers. Your `client_id` is the unique identifier used to identify your Partner Application. Checkr uses this `client_id` to compose a unique link to embed in your application for your customers to use to either sign in to an existing Checkr account, or sign up for a new Checkr account. With an active Partner Application and the "Signup flow" setting enabled, use the following links to point to your staging or production account. **Staging** * Create a new account: https://partners.checkrhq-staging.net/authorize/{client_id}/signup * Connect an existing Checkr account to your application: https://partners.checkrhq-staging.net/authorize/{client_id}/signin * Allow the customer to choose whether to create a new account or link an existing account: https://partners.checkrhq-staging.net/authorize/{client_id} **Production** * Create a new account: https://partners.checkr.com/authorize/{client_id}/signup * Connect an existing Checkr account to your application: https://partners.checkr.com/authorize/{client_id}/signin * Allow the customer to choose whether to create a new account or link an existing account: https://partners.checkr.com/authorize/{client_id} If the "Signup flow" setting is disabled, the /signup URL will always redirect to /signin, and the "Need a Checkr account? Sign up" option will be hidden from the Sign In page. | | | | --- | --- | | ![Sign into Checkr](/assets/signintocheckr.a6a7466fa7bd799476160f8602ab4f19e5483a0f145afc901b676064e376d26e.9c1bb791.png) | ![Sign into Checkr or sign up](/assets/signintocheckrorsignup.25090b43b1b1eaa7155e83c98ac19f010dbd7b748a601be60befaf52ae556c9d.9c1bb791.png) | | *The Sign In page with the "Signup flow" setting enabled vs. disabled* | | ### The Checkr-Hosted Signup flow The Checkr-Hosted Signup flow is the simplest way for customers to create and connect a new Checkr account, and requires the least development effort on your part. Embed a "Connect to Checkr" link within your application and Checkr will collect the necessary user and company information to set up and credential the customer’s Checkr account. Work with your Checkr Partner Manager to understand the best place within your application to embed this link for your customers. ##### Example "Connect to Checkr" link ``` https://partners.checkr.com/authorize/{client_id}?redirect_uri=https://partnerinc.com/checkr/callback&state=79a3ead9-2768-477f-8eca-724890dcf8d6 ``` When embedding the "Connect to Checkr" link in your application, you may also elect to use the following URL parameters to pass additional information and secure your customers’ authentication. * **state** (required): A string to be passed back as a URL parameter on **redirect_uri** upon flow completion. We recommend using **state** to pass through your unique ID of the customer so that you are aware which customer is connecting to your application. * **redirect_uri** (optional): The URL to redirect your user to upon flow completion. This must match the [configured redirect_uri in your Partner Application](#redirect_uri) settings and must use the HTTPS protocol. This must be a static string. Wildcards (*) are not supported. Following this link will direct a user to the Checkr-Hosted Signup flow. This flow consists of 3 steps and requires end users to supply information about themselves, their company, and the reason they are running background checks (also known as "permissible purpose"). Checkr accepts both credit/debit card and ACH information, which may be updated from your customer's Checkr Dashboard at any time. Customers are charged only for the background checks they run. When testing your "Connect to Checkr" implementation, be certain to use an email address which is not associated with the Checkr account hosting your applications. Attempting to sign up for a Checkr account with a user associated with that account will result in a 422 error. [Click here](https://partners.checkr.com/authorize/9340a19f5735e044b040178b) to access a live demo of the Checkr-Hosted Signup flow. | | | | | --- | --- | --- | | ![Welcome screen](/assets/welcome.818fe12273f7632649431ff3b0a54d2d964499abf356e0c713f388c66a8e5742.9c1bb791.png) | ![Sign up screen](/assets/signup.8ec64129891b515b0ff0717116adba168af4cf84302bf3c56b1dbcb4b95714d6.9c1bb791.png) | ![Payment screen](/assets/payment.dc2aa122b197406c8125b12ab9c26a1018a0c8493974f9d4b68a4e6fc2cb8ad7.9c1bb791.png) | | *Checkr-Hosted Signup flow* | | | Once your end user has completed the "Connect to Checkr" flow and successfully connected an account, they will be redirected to your defined **redirect_uri** with the **state** parameter you provided, and the **code** that you will use to request an [access token.](#retrieve-an-access-token) The access token grants your application the right to make API calls to Checkr on behalf of your customer. For example: ``` https://partnerinc.com/checkr/callback?code={JWT}&state=79a3ead9-2768-477f-8eca-724890dcf8d6 ``` Check that the `state` parameter string returned matches what you passed initially. If it doesn’t match or doesn’t exist, treat it as a failed connection, surface the error to the user, and redirect them to the start of the flow to try the process again. ##### Retrieve an access token If the `state` string is a match to that initially passed, use the `code` parameter to call the Tokens endpoint and retrieve an `access_token` for your authorized customer. This is a one-time process and the access_token grants your application the right to make API calls to Checkr on behalf of the customer account. See [Error codes](/partners/reference#error-codes) for a list of 422 errors that may be returned for this call. ```sh $ curl -X POST https://api.checkr.com/oauth/tokens \ -d client_id={client_id} \ -d client_secret={client_secret} \ -d code={JWT} ``` ##### Example response ```json { "access_token": "{access_token}", // customer's access token "scope": "read_write", "checkr_account_id": "5d78dfa52ea938723b2f2ba3" // customer's account ID } ``` The authorization code that is passed as a parameter on the `redirect_uri` is specifically used to retrieve an access token for the authorized customer. It can be used only once and expires 5 minutes after creation. Access tokens are long-lived, account-level API keys that are not tied to specific user access. They are valid until revoked, so treat them with care. We recommend storing them encrypted in your application's data store along with the customer account ID (`checkr_account_id`) returned in the response payload. #### Checkr-Hosted Sign In flow and existing Checkr customers This process is available to customers who have an existing Checkr account, but are new to your partner integration. The Checkr-Hosted Sign In flow prompts users to sign into their existing Checkr account to authorize the connection. Only Checkr users with an Admin role within their Checkr account can perform this action. | | | | | --- | --- | --- | | ![Sign in screen](/assets/signin.f84dbc85c2d365bee578fc8cb82e54f70b0373562f4e6498d1a51088d6e2b4e8.9c1bb791.png) | ![Checkr login](/assets/checkrlogin.4a2b4fa0587aa1a0fe670a251789038f57da86f0c47355650089c5cf8a93bf51.9c1bb791.png) | ![Connect to Checkr](/assets/connect.29058ac18c1f76309ec01c2c922b6afd739baf6f0ddd0fc2a3e4f1934a29c969.9c1bb791.png) | | *Checkr-hosted Sign In and authorization flow* | | | ## Customer account credentialing New accounts must be [credentialed](https://docs.checkr.com/#section/Introduction/Get-credentialed) by Checkr’s Customer Success team before they will be allowed to request background checks. We use the information provided by the customer to assess the validity of the business and its permissible purpose. This process generally takes less than 1 business day. Once the credentialing process is complete, Checkr will issue an `account.credentialed` webhook to the `webhook_url` configured during Partner Application setup. We will also notify your customer by email (the technical contact, if present, otherwise the first admin user). If your customer's Checkr account is already credentialed, the `account.credentialed` webhook will be issued immediately after the Connect to Checkr flow is completed. To check the account credentialing status for a customer account, use their `access_token` to call `GET /v1/account`. The account is credentialed if the `authorized` parameter is set to `true`. ## Display customers’ connected state and deauthorization After a customer has connected their Checkr account once, there is no need to perform the action again unless or until the customer's access token is deauthorized. We recommend displaying this connected state in your application to prevent your customers from attempting to create more than one Checkr account or connect more than once. You may also elect to provide your end users the ability to disconnect their Checkr account from your application. Use the Deauthorize endpoint to deprecate a customer's access token. Customers may also deauthorize your application from the Checkr Dashboard. Listen for the `token.deauthorized` webhook for notification of these events. ##### Deauthorize a customer's access token ```sh $ curl -X POST https://api.checkr.com/oauth/deauthorize -u {access_token}: ``` ##### Example response ```json { "access_token": "{access_token}" } ``` Once an `access_token` is deauthorized and the customer account is disconnected from your application, we recommend reflecting this state in your application so that customers can attempt to connect again.