# Advanced Features

### Use the Create Account API

If you collect the information included in the [Checkr Hosted Signup](/partners/getting-started#the-checkr-hosted-signup-flow) flow on your customers’ behalf, use the Account endpoint to provide a more integrated, seamless experience. The Account endpoint can be used to create customer accounts without requiring the customer to complete a Checkr-hosted Signup flow.

The oauth_authorize parameter allows you to determine how your customer authorizes your application to connect to Checkr and order reports.

* By default, this parameter is set to `false`, which requires your customers to provide explicit authorization to your application to create candidates, invitations, and reports in Checkr on your customer’s behalf.
* If set to `true`, Checkr returns the authorization code in the account response. You may then use that access code in the oauth/token call to get an authorized token you can use to create reports/candidates in the customer's Checkr account.


Set `oauth_authorize` to `false` to create the account, then redirect your customers to the [Checkr Hosted Sign In flow](/partners/getting-started#the-checkr-hosted-signup-flow) to sign in and explicitly grant authorization to your application. The authorization **code** will be returned as a URL parameter on your defined `redirect_uri`.

If you send account information and set the `oauth_authorize` parameter to `false`, and then direct your customer to sign-in, their Checkr account will be created, but your customer will not be able to order reports.

For the Accounts and Tokens endpoints, authenticate using an API key generated through the **Account Settings > Developer Settings** page within the Checkr Dashboard. Logs generated from this API call can be accessed from the **Logs** tab in your Partner Checkr account.

Once the authorization code is acquired, use the [Tokens endpoint](/partners/getting-started#retrieve-an-access-token) to retrieve the customer’s access token.

##### Create an account that requires end-user authorization

```sh
$ curl -X POST https://api.checkr.com/v1/accounts -u {API_KEY}: \
	-d client_id={client_id} \
      -d false \
	-d See request body on [docs.checkr.com](https://docs.checkr.com/#operation/createAccount)
```

##### Example response

```json
{
    "id": "dwe2u29j7gg47p8ed7wa",
    "object": "account",
    "name": "Customer Services Inc.",
    "default_compliance_state": "CA",
    "authorized": false,  // false means account is not yet credentialed
    "purpose": "employment",
    "user": {
        "email": "user@email.com",
        "full_name": "Jane Doe"
    },
    "company": {
        "industry": "72",
        "incorporation_state": "MA",
        "dba_name": "Customer Services",
        "website": "https://company.com",
        "tax_id": "123456789",
        "incorporation_type": "corporation",
        "street": "123 Main Street",
        "zipcode": "10200",
        "city": "Brooklyn",
        "state": "NY"
        "phone": "222-222-2222"
    }
    ...
}
```

##### Create an account that implies end-user authorization

```sh
$ curl -X POST https://api.checkr.com/v1/accounts \
    -u 83ebeabdec09f6670863766f792ead24d61fe3f9: \
    -d client_id=56269e3411a549fd07ed8d92 \
    -d name=Acme+Corporation \
    -d default_compliance_state=CA \
    -d purpose=employment \
    -d user[full_name]=Jeanette+Hughes \
    -d user[email]=user@example.com \
    -d company[dba_name]=Acme \
    -d company[industry]=72 \
    -d company[street]=123+Main+Street \
    -d company[city]=San Francisco \
    -d company[state]=CA \
    -d company[zipcode]=94107 \
    -d company[tax_id]=123456789 \
    -d company[incorporation_state]=CA \
    -d company[incorporation_type]=association \
    -d company[phone]=206-555-0100 \
    -d company[website]=https%3A%2F%2Fwww.example.com
```

##### Example response

```json
{
  "id": "e44aa283528e6fde7d542194",
  "object": "account",
  "adverse_action_email": "john.doe@example.com",
  "api_authorized": true,
  "authorized": true,
  "available_screenings": [
    "county_civil_search",
    "county_criminal_search",
    "municipal_criminal_search",
    "employment_verification",
    "federal_civil_search",
    "federal_criminal_search",
    "motor_vehicle_report",
    "national_criminal_search",
    "sex_offender_search",
    "ssn_trace",
    "state_criminal_search"
  ],
  "billing_email": "john.doe@example.com",
  "company": {
    "name": "Acme Corporation",
    "dba_name": "ACME",
    "street": "123 Main St",
    "city": "Wilmington",
    "state": "DE",
    "zipcode": "19801",
    "phone": "206-555-0100",
    "website": "https://example.com",
    "industry": "52-59",
    "incorporation_state": "DE",
    "incorporation_type": "llc"
  },
  "compliance_contact_email": "compliance.team@example.com",
  "created_at": "2020-01-07T00:26:49Z",
  "default_compliance_city": "San Francisco",
  "default_compliance_state": "CA",
  "geos_required": false,
  "name": "Acme Corp",
  "purpose": "employment",
  "support_email": "support@example.com",
  "support_phone": "206-555-0188",
  "technical_contact_email": "jane.smith@example.com",
  "uri": "/v1/accounts/e44aa283528e6fde7d542194",
  "uri_name": "acme-corp"
}
```

## Pre-credential customers

If using the Account API to create customer accounts, you must also be able to pre-credential customer accounts for use with the POST /accounts call.

To pre-credential customer accounts, you must:

* collect and store the information required to verify that the company is a legitimate business.
* collect and store the information required to verify that the use of the Checkr platform is for a permissible/employment purpose.
* collect and store the customer’s tax ID/EIN or state of incorporation.
* perform ongoing or annual verification that the customer’s company is legitimate and that they are using the platform for a permissible purpose.
* store the customer’s credentialing status for audit and recordkeeping purposes.


If any required parameters are missing or cannot be validated from the `POST /accounts` call, Checkr will reject the account creation request. Please refer to the Accounts API documentation to review required fields.

For more information, see [Get credentialed to run background checks](https://help.checkr.com/hc/en-us/articles/360044040154-Get-credentialed-to-run-background-checks) in the Checkr Help Center, and [Get Credentialed](https://docs.checkr.com/#section/Introduction/Get-credentialed) in the Checkr APIs.

## Create a self-hosted Reports flow

A more advanced method to integrating background checks into your application is to use the [Reports](https://docs.checkr.com/#tag/Reports) resource to build a custom, self-hosted flow. Once all required information is present on the Candidate resource, creating a Report will initiate the background check.

In this flow, you must collect and store both the candidate’s information and their consent within your application.

As an end user ordering consumer reports, your customers have certain responsibilities under the Fair Credit Reporting Act (FCRA). As your partner in background check screening, Checkr helps facilitate compliance with the FCRA in a few ways. Building a self-hosted Reports flow requires that you take on these obligations on behalf of your customers, including providing candidates the appropriate state- and city-specific disclosures for each screening type. For more information on your obligations under FCRA, and Checkr’s responsibilities as a Consumer Reporting Agency (CRA), check out our helpful [Compliance resources](https://help.checkr.com/hc/en-us/sections/203637107-Compliance) in the Help Center, particularly our articles about [obligations under FCRA](https://help.checkr.com/hc/en-us/articles/216557368-What-is-the-Fair-Credit-Reporting-Act-FCRA-) and [disclosures and authorizations](https://help.checkr.com/hc/en-us/articles/360000144867-Disclosure-and-authorization).

You must also store your candidates’ consent to the background check, both to maintain proof that consent was granted, and to provide proof of consent for Checkr’s ongoing evaluation of partner compliance (annual compliance audits).

If you are interested in building a self-hosted Reports flow, work with your Checkr Partner Manager to understand the required disclosures and authorizations and PII that you must collect from the candidate before creating a report. Your Checkr Partner Manager must also review your workflow before you will be approved to use the Reports API in production.

Some screening types are not supported with the Reports flow, such as credit checks and others that require significant data entry like employment and education verifications. For more information, see [Reports](https://docs.checkr.com/#tag/Reports) in the Checkr API documentation.

## Screening-level statuses

In addition to providing a high-level report status (Pending, Clear, or Consider), you may also wish to expose the status of individual screenings within the Package. The most straightforward way to do this is to use the [Embedded Resource](https://docs.checkr.com/#section/Reference/Embedding-Resources) feature. Use the `include` parameter to expand the screening objects in the Report resource in order to fetch the individual statuses.

##### Retrieve common screening statuses

```sh
$ curl -X GET https://api.checkr.com/v1/reports/{report_id}?include=ssn_trace,county_criminal_searches,global_watchlist_search,national_criminal_search,sex_offender_search,motor_vehicle_report -u {access_token}:
```

See [List existing Packages](https://docs.checkr.com/#operation/packagesList) in the Checkr API documentation for a list of available screenings.

##### Example response

```json
{
      "id": "4722c07dd9a10c3985ae432a",
      "object": "report",
      "uri": "/v1/reports/4722c07dd9a10c3985ae432a",
      "status": "pending",  // overall report status
      "ssn_trace": {
          "id": "e44aa283528e6fde7d542194",
          "object": "ssn_trace",
          "uri": "/v1/ssn_traces/539fd88c101897f7cd000001",
          "status": "clear",  // ssn trace status
          ...
      },
      "county_criminal_searches": [
          {
            "id": "58845a3ea0fcd97136763136",
            "object": "county_criminal_search",
            "uri": "/v1/county_criminal_searches/58845a3ea0fcd97136763136",
            "status": "clear",  // county criminal search status
            ...
          },
          {
            "id": "58845a3ea0fcd97136763137",
            "object": "county_criminal_search",
            "uri": "/v1/county_criminal_searches/58845a3ea0fcd97136763137",
            "status": "pending",  // county criminal search status
            ...
          }
      ]
      ...
}
```

## Checkr Assessments

Some customers may use Checkr Assess to apply pre-adjudication rules to returned records. You may choose to surface these assessments when displaying these records within your application.

Use the [Assessments](https://docs.checkr.com/#tag/Assessments) endpoint to retrieve your customers’ applied assessments for reports.

##### Retrieve applied assessments

```sh
$ curl -X GET https://api.checkr.com/v1/reports/{report_id}/assessments \
    -u {access_token}:
```

##### Example response

```json
{
  "data": [
    {
      "value": "eligible",
      "created_at": "2014-01-18T12:34:00Z",
      "ruleset": {
        "id": "e44aa283528e6fde7d542194",
        "name": "Ruleset for employees in Arizona",
        "version": {
          "number": 5
        }
      },
      "results": [
        {
          "value": "eligible",
          "assessed_objects": [
            {
              "object_id": "e44aa283528e6fde7d542194",
              "object_type": "criminal_charge"
            }
          ],
          "rule": {
            "name": "Allow dismissed charges rule",
            "type": "lookback_period"
          }
        }
      ]
    }
  ],
  "object": "list",
  "count": 1
}
```

## Sync your Partner Account Hierarchy to Checkr

If your system supports its own account hierarchy, you may wish to sync your hierarchy with your customers' accounts on a regular cadence. For example, if your application has a node (such as a department or line of business), and you wish to create new nodes within your application using the /hierarchy endpoint, you may wish to keep hierarchies defined within your application in sync with those your customers have defined within their Checkr account.

This approach may present some significant challenges. Managing two separate account hierarchies (your application's and your customers') and keeping them in sync with one another requires careful planning. Be certain to work with your Checkr Partner Manager to determine if this approach is required for your integration.

For more information on using the hierarchy endpoint for syncing your hierarchy to your customers' Checkr accounts, see the [Account Hierarchy](https://docs.checkr.com/#operation/updateAccountHierarchy) in the Checkr API documentation.