Getting Started

The following sections will walk you through the steps necessary to get started running background checks with the Checkr API:

We assume you are familiar with the curl command, which is used for all examples in the the Checkr API documentation.

 

Get your API key

Once you have access set up to log in to Checkr, go to your Developer Settings page and get a copy of your Test API Key. Your Test API key is a 40 character hexadecimal key that the Checkr API uses to identify your account. See the Development section for information about test Social Security Numbers and Driver's License numbers you can use for running test Reports.

Your production API key is also available on the Developer Settings page. Note that your production key will not be enabled for Reports until you contact [email protected] and request that your account be enabled for live requests.

 

How to authenticate

Authentication with the Checkr API is done by using HTTP Basic authentication, with your API key as the username and an empty password. When using curl, you can use the -u option to specify your api key. (Note that the colon following the API key in the examples is important. It tells curl to send an empty password.)

Example authentication

$ curl https://api.checkr.com \
        -u YOUR_TEST_API_KEY:
 

Create a Candidate

Now let's create a test Candidate. Remember to replace "YOUR_TEST_API_KEY" with your actual test API key in the curl example on the right. See Candidate for more details on creating Candidates.

CREATE A TEST CANDIDATE

curl -X POST https://api.checkr.com/v1/candidates \
        -u YOUR_TEST_API_KEY: \
        -d first_name=Your \
        -d middle_name=Full \
        -d last_name=Name \
        -d email=your.name@example.com \
        -d phone=5555555555 \
        -d zipcode=90401 \
        -d dob=1970-01-22 \
        -d ssn=111-11-2001 \
        -d driver_license_number=F1112001 \
        -d driver_license_state=CA
 

Candidate Creation Response

Note that the response returns a full Candidate object, including the ID of the Candidate and a uri that points to the new Candidate object. Note the ID for this new Candidate object, which you'll need to use when creating a Report in the next step.

TEST CANDIDATE CREATION RESPONSE

{
  "id": "CANDIDATE_ID",
  "object": "test_candidate",
  "uri": "/v1/candidates/CANDIDATE_ID",
  "created_at": "2015-05-13T23:12:22Z",
  "first_name": "Your",
  "middle_name": "Full",
  "no_middle_name": false,
  "last_name": "Name",
  "mother_maiden_name": null,
  "email": "[email protected]",
  "phone": "5555555555",
  "zipcode": null,
  "dob": "1970-01-22",
  "ssn": "XXX-XX-2001",
  "driver_license_number": "F1112001",
  "driver_license_state": "CA",
  "previous_driver_license_number": null,
  "previous_driver_license_state": null,
  "copy_requested": false,
  "custom_id": null,
  "report_ids": [],
  "geo_ids": []
}
 

Create a Report

Now we'll create a Report for the Candidate created in the previous step. Plug in your actual test API key and Candidate ID to the curl command on the right.

There are four packages supported: tasker_standard, tasker_pro, driver_standard, and driver_pro:

ReportDescription
tasker_standardBackground search with 1 county criminal search
tasker_proBackground search with unlimited county criminal searches
driver_standardAdds Motor Vehicle Report to tasker_standard
driver_proAdds Motor Vehicle Report to tasker_pro

See Pricing for full details and pricing.

CREATE A TEST REPORT

$ curl -X POST https://api.checkr.com/v1/reports \
        -u YOUR_TEST_API_KEY: \
        -d package=driver_pro \
        -d candidate_id=CANDIDATE_ID
 

Report Creation Response

Note that the response returns a full Report object, including the ID of the Report and a uri that points to the new Report object. Note the ID for this new Report object, which you'll need to use when retrieving your Report.

TEST REPORT CREATION RESPONSE

{
  "id": "REPORT_ID",
  "object": "test_report",
  "uri": "/v1/reports/REPORT_ID",
  "status": "pending",
  "created_at": "2015-05-14T17:45:34Z",
  "completed_at": null,
  "turnaround_time": null,
  "due_time": "2015-05-16T10:23:21Z",
  "package": "driver_pro",
  "candidate_id": "CANDIDATE_ID",
  "ssn_trace_id": "SSN_TRACE_ID",
  "sex_offender_search_id": "SEX_OFFENDER_SEARCH_ID",
  "national_criminal_search_id": "NATIONAL_CRIMINAL_SEARCH_ID",
  "federal_criminal_search_id": null,
  "county_criminal_search_ids": [],
  "motor_vehicle_report_id": "MOTOR_VEHICLE_REPORT_ID",
  "state_criminal_search_ids": [],
  "document_ids": []
}
 

Retrieve the Report

Now we'll retrieve the Report we created in the previous step. Plug in your actual test API key and Report ID to the curl command on the right.

Retrieve the Report

$ curl https://api.checkr.com/v1/reports/REPORT_ID \
        -u YOUR_TEST_API_KEY:
    
 

Retrieve Report Response

Note that the Report is now a full Report with a status of "clear", indicating that no violations or criminal background have come up for this Report. See Development for more information about test Social Security Numbers and Driver's License numbers.

See Embedding if you wish to embed full contents of the various screenings (SSN Trace, Sex Offender Search, Global Watchlist Search, etc.) in the server response. You can also retrieve those resources using the IDs provided in the server response.

RETRIEVE REPORT RESPONSE

{
  "id": "REPORT_ID",
  "object": "test_report",
  "uri": "/v1/reports/REPORT_ID",
  "status": "clear",
  "created_at": "2015-05-14T17:45:34Z",
  "completed_at": "2015-05-14T17:45:39Z",
  "upgraded_at": null,
  "turnaround_time": 5,
  "package": "driver_pro",
  "tags": null,
  "candidate_id": "CANDIDATE_ID",
  "ssn_trace_id": "SSN_TRACE_ID",
  "sex_offender_search_id": "SEX_OFFENDER_SEARCH_ID",
  "national_criminal_search_id": "NATIONAL_CRIMINAL_SEARCH_ID",
  "federal_criminal_search_id": null,
  "county_criminal_search_ids": [
    "COUNTY_CRIMINAL_SEARCH_ID_1",
    "COUNTY_CRIMINAL_SEARCH_ID_2",
    "COUNTY_CRIMINAL_SEARCH_ID_3"
  ],
  "motor_vehicle_report_id": "MOTOR_VEHICLE_REPORT_ID",
  "state_criminal_search_ids": [],
  "document_ids": []
}
 

Conclusion

Now you know how to create Candidates and create and retrieve Reports! Continue reading below, or see the index to the left for more information about the Checkr API.

 

Authentication

Example authentication

$ curl https://api.checkr.com \
-u 83ebeabdec09f6670863766f792ead24d61fe3f9:
 

Webhooks

Whenever an event occurs that would be relevant to your application, we'll submit a POST to your designated Webhook URL with information about the event.
In order to receive webhooks, you will need to configure a Webhook URL in your Account Settings

The User-Agent for the requests will have the prefix Checkr-Webhook/.

Events

report.created
Status: 'pending'
A new Report has been created.
report.upgraded
Status: 'pending'
A Report has been upgraded. Upgrades can be triggerred either from an API call or from our dashboard ("Upgrade" button). This is useful if you want to run a package (eg: MVR) and then upgrade it on completion (eg: to add a criminal search).
report.completed
Status: 'clear', 'consider'
A Report has been completed.
report.suspended
Status: 'suspended'
A Report has been suspended. This occurs when we are waiting for an applicant to provide additional documentation.
report.resumed
Status: 'pending'
A Report has resumed. This happens once an applicant has provided documentation to a previously "suspended" Report.
report.disputed
Status: 'dispute'
A Report has been disputed by an applicant. Once a dispute has been completed, we will trigger report.completed webhook again with the appropriate Report status.
report.pre_adverse_action
Status: 'consider'
The pre-adverse action notice has been sent to the candidate of that report.
report.post_adverse_action
Status: 'consider'
The final adverse action notice has been sent to the candidate of that report.
report.engaged
Status: 'pending', 'clear', 'consider', 'suspended'
A Report has been adjudicated as "engaged". This is useful to keep track of all the applicants you have officially engaged, or simply the ones that had a "consider" background check report but for who you still decided to move forward with. This can be triggered either from an API call or from the dahsboard ("Engage" button).
candidate.created A new Candidate has been created.
candidate.id_required An exception has been raised requiring a copy of the Candidate's identification.
candidate.driver_license_required An exception has been raised requiring a copy of the Candidate's driver's license.

Attributes

id: string
object: string
'event'
type: string
values: 'report.created', 'report.completed'
created_at timestamp
iso 8601 format
webhook_url string
data hash
object associated with the event

Responding to webhooks


To acknowledge receipt of a webhook, your endpoint should return a 2xx HTTP status code. Any other information returned in the response headers or response body is ignored.

If a webhook is not successfully received for any reason, Checkr will continue trying to send it every minute for 10 minutes, then every hour for 24 hours.

Webhook logs can be found on the dashboard: https://dashboard.checkr.com/webhook_logs


Securing webhooks


For security reasons, you might want to verify that the requests you receive come from Checkr.

We pass along a hash signature with each request in the header X-Checkr-Signature.
When you receive a request, you can compute a hash and ensure that the one from Checkr matches.

The hash signature is generated with the HMAC algorithm, using your API key as a key and SHA256 digest mode.

EXAMPLE WEBHOOK PAYLOAD

{
  "id": "507f1f77bcf86cd799439011",
  "object": "event",
  "type": "report.completed",
  "created_at": "2014-01-18T12:34:00Z",
  "webhook_url": "https://yourcompany.com/checkr/incoming",
  "data": {
    "object": {
      "id": "4722c07dd9a10c3985ae432a",
      "object": "report",
      "uri": "/v1/reports/532e71cfe88a1d4e8d00000d",
      "created_at": "2014-01-18T12:34:00Z",
      "received_at": "2014-01-18T12:34:00Z",
      "status": "clear",
      "package": "driver_pro",
      "candidate_id": "e44aa283528e6fde7d542194",
      "ssn_trace_id": "539fd88c101897f7cd000001",
      "sex_offender_search_id": "539fd88c101897f7cd000008",
      "national_criminal_search_id": "539fd88c101897f7cd000006",
      "county_criminal_search_ids": [
        "539fdcf335644a0ef4000001",
        "532e71cfe88a1d4e8d00000c"
      ],
      "state_criminal_search_ids": [
        "539fdcf335644a0ef4000003",
        "532e71cfe88a1d4e8d000004"
      ],
      "motor_vehicle_report_id": "539fd88c101897f7cd000007"
    }
  }
}

EXAMPLE HASH SIGNATURE COMPUTATION

echo -n "${request_body}" | openssl dgst -sha256 -hmac "${api_key}"
 

Development

You can make test API calls by using your test API key. Test API requests are free and return fake data.

To help you integrate with our API, we provide a few tests SSNs and driver licenses that will always return a predictable result.
If you use different identifiers, the screenings will stay pending.


Test SSNs


Test SSNs affect the SSN trace and all the criminal screenings.

111-11-2001 Criminal screenings with status 'clear'
111-11-2002 Criminal screenings with status 'consider'

Test driver licenses


Test driver licenses affect only the motor vehicle report.

F1112001 (CA) MVR with status 'clear'
F1112002 (CA) MVR with status 'consider'

You can use a service like RequestBin to do webhook development without setting up a server.

 

Embedding Resources

By default, an API response contains the requested resource, and provides the ids of related resources. You can also request related resources to be embedded in the initial response.

The include parameter specifies the names of resources that should be embedded in the response. Resources to embed should be comma-separated.

EXAMPLE REQUEST

$ curl -X GET https://api.checkr.com/v1/reports/59b650f567e1dd0f01422b92?include=candidate,ssn_trace,county_criminal_searches -u 83ebeabdec09f6670863766f792ead24d61fe3f9:

Pagination

Pagination is enabled for endpoints that return a list of records.
There are two parameters that control pagination: page, which specifies the page number to retrieve, and per_page, which indicates how many records each page should contain.

Parameters

per_page: integer
between 0 and 100
page: integer
greater than or equal to 1
Paginated responses include the following attributes:

Attributes

data: array
list of objects
object: string
'list'
next_href: string
URI to fetch the next page of results
previous_href: string
URI to fetch the previous page of results
count: integer
the total number of items

EXAMPLE PAGINATED REQUEST

$ curl -X GET https://api.checkr.com/v1/candidates?page=2&per_page=25 -u 83ebeabdec09f6670863766f792ead24d61fe3f9:

EXAMPLE PAGINATED PAYLOAD

{
  "data": [
    {
      "id": "e44aa283528e6fde7d542194",
      "object": "candidate",
      "uri": "/v1/candidates/e44aa283528e6fde7d542194",
      "created_at": "2014-01-18T12:34:00Z",
      "first_name": "John",
      "middle_name": "Alfred",
      "no_middle_name": false,
      "last_name": "Smith",
      "mother_maiden_name": null,
      "email": "[email protected]",
      "phone": "5555555555",
      "zipcode": "90401",
      "dob": "1970-01-22",
      "ssn": "XXX-XX-4645",
      "driver_license_number": null,
      "driver_license_state": null,
      "previous_driver_license_number": null,
      "previous_driver_license_state": null,
      "copy_requested": false,
      "custom_id": null,
      "report_ids": [
      ]
    },
    {
      "id": "8b6eb2bf554ebbef7b6f885a",
      "object": "candidate",
      "uri": "/v1/candidates/8b6eb2bf554ebbef7b6f885a",
      "created_at": "2014-01-18T12:34:00Z",
      "first_name": "Michael",
      "middle_name": null,
      "no_middle_name": true,
      "last_name": "Johnson",
      "mother_maiden_name": null,
      "email": "[email protected]",
      "phone": "5555555555",
      "zipcode": "94407",
      "dob": "1970-01-22",
      "ssn": "XXX-XX-8605",
      "driver_license_number": null,
      "driver_license_state": null,
      "previous_driver_license_number": null,
      "previous_driver_license_state": null,
      "copy_requested": false,
      "custom_id": null,
      "report_ids": [
      ]
    }
  ],
  "object": "list",
  "next_href": null,
  "previous_href": "http://api.checkr.com/v1/candidates?page=1&per_page=25",
  "count": 27
}
 

Candidate

Represents a candidate to be screened.

Attributes

id: string
object: string
'candidate'
uri: string
uri of the resource
created_at: timestamp
iso 8601 format
first_name: string
middle_name: string
no_middle_name: boolean
default: false
last_name: string
mother_maiden_name: string
email: string
phone: string
format: XXXXXXXXXX
zipcode: string
dob: date
format: YYYY-MM-DD
ssn: string
format: XXX-XX-XXXX
driver_license_number: string
driver_license_state: string
format: ST
previous_driver_license_number: string
previous_driver_license_state: string
format: ST
copy_requested: boolean
default: false
custom_id: string
report_ids: array
list of report ids
geo_ids: array
list of geo ids
document_ids: array
list of document ids



EXAMPLE RESOURCE

  {
    "id": "e44aa283528e6fde7d542194",
    "object": "candidate",
    "uri": "/v1/candidates/e44aa283528e6fde7d542194",
    "created_at": "2014-01-18T12:34:00Z",
    "first_name": "John",
    "middle_name": "Alfred",
    "no_middle_name": false,
    "last_name": "Smith",
    "mother_maiden_name": null,
    "email": "[email protected]",
    "phone": "5555555555",
    "zipcode": "90401",
    "dob": "1970-01-22",
    "ssn": "XXX-XX-4645",
    "driver_license_number": "F211165",
    "driver_license_state": "CA",
    "previous_driver_license_number": "F1501739",
    "previous_driver_license_state": "CA",
    "copy_requested": false,
    "custom_id": null,
    "report_ids": [
      "532e71cfe88a1d4e8d00000d"
    ],
    "geo_ids": [
      "79f943e212cce7de21c054a8",
      "7299c2c22ebb19abb0688a6c"
    ],
    "document_ids": []
  }

Create a new Candidate

This request is used to create a new Candidate.

Note: To support use of the Invitations API (in which case, the invitation apply form would collect a Candidate's personal information), the only strictly required Candidate attribute is email.

However, in most cases, additional personal information will be required to request a Report for a Candidate.

Required attributes would include:

  • first_name
  • middle_name or no_middle_name
  • last_name
  • dob

If the Report's package includes any type of criminal check, the following will be required:

  • ssn
  • zipcode

If the Report's package includes a Motor Vehicle Report (MVR), the following will be required:

  • driver_license_number
  • driver_license_state

Validation for these attributes is performed when requesting a Report, as the requirements depend on the Package.

Parameters

first_name: string
middle_name: string
no_middle_name: boolean
default: false
last_name: string
mother_maiden_name: string
email: string required
phone: string
zipcode: string
dob: date
format: YYYY-MM-DD
ssn: string
format: XXX-XX-XXXX
driver_license_number: string
driver_license_state: string
format: ST
previous_driver_license_number: string
previous_driver_license_state: string
format: ST
copy_requested: boolean
default: false
custom_id: string
geo_ids: array[string]

Returns a representation of the Candidate.

DEFINITION

POST https://api.checkr.com/v1/candidates

EXAMPLE REQUEST

$ curl -X POST https://api.checkr.com/v1/candidates \
              -u 83ebeabdec09f6670863766f792ead24d61fe3f9: \
              -d first_name=John \
              -d middle_name=Alfred \
              -d last_name=Smith \
              -d email=john.smith@gmail.com \
              -d phone=5555555555 \
              -d zipcode=90401 \
              -d dob=1970-01-22 \
              -d ssn=543-43-4645 \
              -d driver_license_number=F211165 \
              -d driver_license_state=CA

Update an existing Candidate

This request is used to update an existing Candidate.

Note: Candidates cannot be updated after a Report has been ordered for them.

Parameters

first_name: string
middle_name: string
no_middle_name: boolean
last_name: string
email: string
phone: string
zipcode: string
dob: date
format: YYYY-MM-DD
ssn: string
format: XXX-XX-XXXX
driver_license_number: string
driver_license_state: string
format: ST
previous_driver_license_number: string
previous_driver_license_state: string
format: ST
copy_requested: boolean
custom_id: string
geo_ids: array[string]

Returns a representation of the Candidate.

DEFINITION

POST https://api.checkr.com/v1/candidates/:id

EXAMPLE REQUEST

$ curl -X POST https://api.checkr.com/v1/candidates/e44aa283528e6fde7d542194 \
              -u 83ebeabdec09f6670863766f792ead24d61fe3f9: \
              -d first_name=John \
              -d middle_name=Alfred \
              -d last_name=Smith \
              -d email=john.smith@gmail.com \
              -d phone=5555555555 \
              -d zipcode=90401 \
              -d dob=1970-01-22 \
              -d ssn=543-43-4645 \
              -d driver_license_number=F211165 \
              -d driver_license_state=CA

Retrieve an existing Candidate

This request is used to retrieve existing Candidates.

Parameters

id: string required

Returns a representation of the Candidate.

DEFINITION

GET https://api.checkr.com/v1/candidates/:id

EXAMPLE REQUEST

$ curl -X GET https://api.checkr.com/v1/candidates/e44aa283528e6fde7d542194 -u 83ebeabdec09f6670863766f792ead24d61fe3f9:

List existing Candidates

This request is used to list existing Candidates.

Parameters

email: string
filter candidates by email
full_name: string
filter candidates by full name
adjudication: string
filter candidates by adjudication
custom_id: string
filter candidates by custom_id
created_after: date
format: YYYY-MM-DD
filter candidates created after this timestamp
created_before: date
format: YYYY-MM-DD
filter candidates created before this timestamp
geo_id: string
filter candidates by geo_id

Returns a list of paginated Candidates matching the filter(s).

DEFINITION

GET https://api.checkr.com/v1/candidates

EXAMPLE REQUEST

$ curl -X GET https://api.checkr.com/v1/candidates -u 83ebeabdec09f6670863766f792ead24d61fe3f9:

EXAMPLE PAYLOAD

{
  "data": [
    {
      "id": "e44aa283528e6fde7d542194",
      "object": "candidate",
      "uri": "/v1/candidates/e44aa283528e6fde7d542194",
      "created_at": "2014-01-18T12:34:00Z",
      "first_name": "John",
      "middle_name": "Alfred",
      "no_middle_name": false,
      "last_name": "Smith",
      "mother_maiden_name": null,
      "email": "[email protected]",
      "phone": "5555555555",
      "zipcode": "90401",
      "dob": "1970-01-22",
      "ssn": "XXX-XX-4645",
      "driver_license_number": null,
      "driver_license_state": null,
      "previous_driver_license_number": null,
      "previous_driver_license_state": null,
      "copy_requested": false,
      "custom_id": null,
      "report_ids": [
      ],
      "geo_ids": [
      ]
    },
    {
      "id": "8b6eb2bf554ebbef7b6f885a",
      "object": "candidate",
      "uri": "/v1/candidates/8b6eb2bf554ebbef7b6f885a",
      "created_at": "2014-01-18T12:34:00Z",
      "first_name": "Michael",
      "middle_name": null,
      "no_middle_name": true,
      "last_name": "Johnson",
      "email": "[email protected]",
      "phone": "5555555555",
      "zipcode": "94407",
      "dob": "1970-01-22",
      "ssn": "XXX-XX-8605",
      "driver_license_number": null,
      "driver_license_state": null,
      "previous_driver_license_number": null,
      "previous_driver_license_state": null,
      "copy_requested": false,
      "custom_id": null,
      "report_ids": [
      ],
      "geo_ids": [
      ]
    }
  ],
  "object": "list",
  "next_href": null,
  "previous_href": null,
  "count": 2
}
 

Invitation

Represents a background check invitation. The candidate will receive an email to submit their information.

Attributes

id: string
object: string
'invitation'
uri: string
uri of the resource
status: string
values: 'pending', 'completed', 'expired'
created_at: timestamp
iso 8601 format
expires_at: timestamp
iso 8601 format
completed_at: timestamp
iso 8601 format
package: string
values: 'tasker_standard', 'tasker_pro', 'driver_standard', 'driver_pro'
candidate_id: string
id of the candidate screened



INVITATION RESOURCE

{
    "id": "RESOURCE_ID",
    "status": "pending",
    "uri": "/v1/invitations/RESOURCE_ID",
    "invitation_url": "INVITATION_URL",
    "completed_at": null,
    "deleted_at": null,
    "expires_at": "2015-05-21T17:45:34Z",
    "package": "package",
    "object": "invitation",
    "created_at": "2015-05-14T17:45:34Z",
    "candidate_id": "CANDIDATE_ID"
}

Retrieve existing Invitations

This request is used to retrieve existing Invitations.

Parameters

status string
values: 'pending', 'complete', 'expired'
candidate_id string

Returns a list of Invitations.

DEFINITION

GET https://api.checkr.com/v1/invitations

EXAMPLE REQUEST

curl -X GET https://api.checkr.com/v1/invitations \
            -u 83ebeabdec09f6670863766f792ead24d61fe3f9: \
            -d status=pending

Retrieve an existing Invitation

This request is used to retrieve existing Invitations.

Parameters

id: string required

Returns a representation of the Invitation.

DEFINITION

GET https://api.checkr.com/v1/invitations/:id

EXAMPLE REQUEST

curl -X GET https://api.checkr.com/v1/invitations/3c0a0ca94caaab6ca9634f76 -u 83ebeabdec09f6670863766f792ead24d61fe3f9:

Create a new Invitation

This request is used to create a new Invitation.

Parameters

package: string required
candidate_id: string required

Returns a representation of the Invitation.

DEFINITION

POST https://api.checkr.com/v1/invitations

EXAMPLE REQUEST

curl -X POST https://api.checkr.com/v1/invitations
            -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
            -d candidate_id=e44aa283528e6fde7d542194
            -d package=driver_pro

Cancel an existing Invitation

This request is used to cancel an existing Invitation.

Parameters

id: string required

Returns a representation of the Invitation.

DEFINITION

DELETE https://api.checkr.com/v1/invitations/:id

EXAMPLE REQUEST

curl -X DELETE https://api.checkr.com/v1/invitations/4722c07dd9a10c3985ae432a -u 83ebeabdec09f6670863766f792ead24d61fe3f9
 

Report

Represents a background check report. Depending on the selected package, a report can include the following screenings: SSN trace, sex offender search, national criminal search, county criminal searches and motor vehicle report.

Attributes

id: string
object: string
'report'
uri: string
uri of the resource
status: string
values: 'pending', 'clear', 'consider', 'suspended', 'dispute'
created_at: timestamp
iso 8601 format
completed_at: timestamp
iso 8601 format
turnaround_time: integer
seconds
due_time: timestamp
iso 8601 format
adjudication: string

default: null
values: 'engaged', 'pre_adverse_action', 'post_adverse_action'
package: string
short name of package, values like 'tasker_standard', 'tasker_pro', 'driver_standard', 'driver_pro'
candidate_id: string
id of the Candidate screened
ssn_trace_id: string
id of the SSN trace report
sex_offender_search_id: string
id of the Sex offender search
national_criminal_search_id: string
id of the National criminal search
county_criminal_search_ids: array
list of County criminal search ids
motor_vehicle_report_id: string
id of the Motor vehicle report
state_criminal_searches: array
list of State criminal search ids
document_ids: array
list of Document ids



EXAMPLE RESOURCE

  {
    "id": "4722c07dd9a10c3985ae432a",
    "object": "report",
    "uri": "/v1/reports/4722c07dd9a10c3985ae432a",
    "status": "clear",
    "created_at": "2014-01-18T12:34:00Z",
    "completed_at": "2014-01-18T12:35:30Z",
    "turnaround_time": 90,
    "due_time": "2014-01-19T11:28:31Z",
    "adjudication": "engaged",
    "package": "driver_pro",
    "candidate_id": "e44aa283528e6fde7d542194",
    "ssn_trace_id": "539fd88c101897f7cd000001",
    "sex_offender_search_id": "539fd88c101897f7cd000008",
    "national_criminal_search_id": "539fd88c101897f7cd000006",
    "county_criminal_search_ids": [
      "539fdcf335644a0ef4000001",
      "532e71cfe88a1d4e8d00000c"
    ],
    "motor_vehicle_report_id": "539fd88c101897f7cd000007",
    "state_criminal_search_ids": [
      "539fdcf335644a0ef4000003",
      "532e71cfe88a1d4e8d000004"
    ],
    "document_ids": []
  }

Retrieve an existing Report

This request is used to retrieve existing Reports.

Parameters

id: string required

Returns a representation of the Report.

DEFINITION

GET https://api.checkr.com/v1/reports/:id

EXAMPLE REQUEST

$ curl -X GET https://api.checkr.com/v1/reports/4722c07dd9a10c3985ae432a -u 83ebeabdec09f6670863766f792ead24d61fe3f9:

Create a new Report

This request is used to create a new Report.

Parameters

package: string required
candidate_id: string required

Returns a representation of the Report.

DEFINITION

POST https://api.checkr.com/v1/reports

EXAMPLE REQUEST

$ curl -X POST https://api.checkr.com/v1/reports \
              -u 83ebeabdec09f6670863766f792ead24d61fe3f9: \
              -d package=driver_pro \
              -d candidate_id=e44aa283528e6fde7d542194

Update an existing Report

This request is used to update an existing Report. For now, you can only update its package or its adjudication.

Parameters

package: string optional
adjudication: string optional
Note: Either package or adjudication is required

Returns a representation of the Report.

The Package of a Report cannot be updated if it has an Adverse Action with the status: 'complete' or 'dispute'. To proceed, cancel the Adverse Action or create a new Report.

DEFINITION

POST https://api.checkr.com/v1/reports/:id

EXAMPLE REQUEST

$ curl -X POST https://api.checkr.com/v1/reports/4722c07dd9a10c3985ae432a \
              -u 83ebeabdec09f6670863766f792ead24d61fe3f9: \
              -d package=driver_pro
 

Package

Represents the screenings that will be ran for a Report.

Attributes

id: string
object: string
'package'
uri: string
uri of the resource
created_at: timestamp
iso 8601 format
name: string
the human-readable name of the Package.
slug: string
the unique key identifier of the Package.
screenings: array[object]
list of screenings

For screenings, the type attribute can take any of the following values:

  • ssn_trace
  • motor_vehicle_report
  • sex_offender_search
  • global_watchlist_search
  • national_criminal_search
  • federal_criminal_search
  • federal_civil_search
  • county_criminal_search
  • county_civil_search
  • eviction_search
  • employment_verification
  • education_verification
  • drug_screening

In addition, some screenings require a subtype:

  • county_criminal_search:
    • 7years
    • current
  • county_civil_search:
    • 7years
    • current
  • employment_verification:
    • last3
    • current



EXAMPLE RESOURCE

  {
    "id": "e44aa283528e6fde7d542194",
    "object": "package",
    "uri": "/v1/packages/e44aa283528e6fde7d542194",
    "created_at": "2014-01-18T12:34:00Z",
    "name": "Criminal Pro",
    "slug": "criminal_pro",
    "screenings": [
      {
        "type": "ssn_trace",
        "subtype": null
      },
      {
        "type": "county_criminal_search",
        "subtype": "7years"
      }
    ]
  }

Create a new package

This request is used to create a new package.

Parameters

name: string required
slug: string required
screenings: array[object] required

Returns a representation of the package.

DEFINITION

POST https://api.checkr.com/v1/packages

EXAMPLE REQUEST

curl -X POST https://api.checkr.com/v1/packages \
    -H "Content-Type: application/json" \
    -u 83ebeabdec09f6670863766f792ead24d61fe3f9: \
    -d '{ "name": "Motor Vehicle Report", "slug": "mvr_only", "screenings": [ { "type": "motor_vehicle_report", "subtype": null } ] }'

Retrieve an existing package

This request is used to retrieve existing packages.

Parameters

id: string required

Returns a representation of the package.

DEFINITION

GET https://api.checkr.com/v1/packages/:id

EXAMPLE REQUEST

$ curl -X GET https://api.checkr.com/v1/packages/887445e43144af09b3ac9f70 -u 83ebeabdec09f6670863766f792ead24d61fe3f9:

List existing packages

This request is used to list existing packages.

Returns a list of paginated packages.

DEFINITION

GET https://api.checkr.com/v1/packages

EXAMPLE REQUEST

$ curl -X GET https://api.checkr.com/v1/packages -u 83ebeabdec09f6670863766f792ead24d61fe3f9:

EXAMPLE PAYLOAD

{
  "data": [
    {
      "id": "e44aa283528e6fde7d542194",
      "object": "candidate",
      "uri": "/v1/packages/e44aa283528e6fde7d542194",
      "created_at": "2014-01-18T12:34:00Z",
      "name": "Criminal Pro",
      "slug": "criminal_pro",
      "screenings": [
        {
          "type": "ssn_trace",
          "subtype": null
        },
        {
          "type": "county_criminal_search",
          "subtype": "7years"
        }
      ]
    },
    {
      "id": "8b6eb2bf554ebbef7b6f885a",
      "object": "candidate",
      "uri": "/v1/packages/8b6eb2bf554ebbef7b6f885a",
      "created_at": "2014-01-18T12:34:00Z",
      "name": "Criminal Basic",
      "slug": "criminal_basic",
      "screenings": [
        {
          "type": "ssn_trace",
          "subtype": null
        }
      ]
    }
  ],
  "object": "list",
  "next_href": null,
  "previous_href": null,
  "count": 2
}
 

Document

Represents a Document, either related to a Report (eg: PDF report) or a Candidate (eg: Driver's license, Consent).

Attributes

id: string
object: string
'document'
type: string
values: 'pdf_report', 'consent', 'driver_license', 'state_id_card', 'passport', 'ssn_card'
created_at: timestamp
iso 8601 format
download_uri: string
JSON encoded URL of the document.
This URL is valid for 60 minutes.
filezise: integer
The filesize in bytes.
filename: string
The filename.
content_type: string
The file content type.

EXAMPLE RESOURCE

  {
    "id": "4722c07dd9a10c3985ae432a",
    "object": "document",
    "created_at": "2015-02-11T20:01:50Z",
    "download_uri": "https://checkr-documents.checkr.com/download_path",
    "filesize": 8576,
    "filename": "1423684910_candidate_driver_license.jpg",
    "type": "driver_license",
    "content_type": "image/jpeg"
  }

Retrieve a Document

This request is used to retrieve an existing Document.

You can retrieve the Document IDs from the Report or Candidate resources.

You can also embed Documents when requesting a Report or a Candidate.

DEFINITION

GET https://api.checkr.com/documents/:id

EXAMPLE REQUEST

$ curl -X GET https://api.checkr.com/v1/documents/b73f89e14b393979857806f9 -u 83ebeabdec09f6670863766f792ead24d61fe3f9:

EXAMPLE PAYLOAD

{
    "id": "b73f89e14b393979857806f9",
    "object": "document",
    "created_at": "2014-01-18T12:34:00Z",
    "download_uri": "https://checkr-documents.checkr.com/download_path",
    "filesize": 11503,
    "filename": "1423684910_candidate_driver_license.jpg",
    "type": "driver_license",
    "content_type": "image/jpeg"
}
 

Upload a Candidate Document

This request is used to upload a new Candidate Document.

Parameters

type: string required
values: 'consent', 'driver_license', 'state_id_card', 'passport', 'ssn_card'
file: file required
Path to the document on your local file system

Valid MIME types: 'image/gif', 'image/jpeg', 'image/png', 'image/bmp', 'image/tiff', 'application/pdf'

Returns a representation of the uploaded document.

DEFINITION

POST https://api.checkr.com/v1/candidates/:id/documents

EXAMPLE REQUEST

$ curl -X POST https://api.checkr.com/v1/candidates/e44aa283528e6fde7d542194/documents \
        -u 83ebeabdec09f6670863766f792ead24d61fe3f9: \
        -d type=driver_license \
        --form file=@candidate_driver_license.jpg
 

Verification

Represents a link to direct candidates to upload a document. If a candidate needs to upload documents to continue processing their report, a set of Verifications will be available. There are currently two types of Verifications: id and education. id Verifications are used for identity and license purposes, such as ID card or driver’s license. education Verifications are used for documents related to education verification.

Attributes

id: string
object: string
'validation'
uri: string
uri of the resource
created_at: timestamp
iso 8601 format
completed_at: timestamp
iso 8601 format, value will be null if the candidate has not uploaded the required documents, otherwise will contain the date and time that the documents were provided
verification_type: string
values: 'id', 'education'
verification_url: string
URL to direct the candidate to updload documents



EXAMPLE RESOURCE

  {
    "id": "db313e73383710d4fa2f18fd",
    "object": "verification",
    "uri": "https://api.checkr.com/v1/reports/4722c07dd9a10c3985ae432/verifications/db313e73383710d4fa2f18fd",
    "created_at": "2014-01-18T12:34:00Z",
    "completed_at": null,
    "verification_type": "id",
    "verification_url": "http://verifications.checkr.com/db313e73383710d4fa2f18fd"
  }

Retrieve a Report Verification

This request is used retrieve a Verification.

Parameters

id: string required
report_id: string required

Returns a representation of the Verification.

DEFINITION

GET https://api.checkr.com/v1/reports/:report_id/verifications/:id

EXAMPLE REQUEST

$ curl -X GET https://api.checkr.com/v1/reports/4722c07dd9a10c3985ae432a/verifications/db313e73383710d4fa2f18fd -u 83ebeabdec09f6670863766f792ead24d61fe3f9:

List Report Verifications

This request is used to retrieve the collection of Verifications for a particular report. If none are required, the data list will be empty.

Parameters

report_id: string required

Returns a collection of Verifications.

DEFINITION

GET https://api.checkr.com/v1/reports/:report_id/verifications

EXAMPLE REQUEST

$ curl -X GET https://api.checkr.com/v1/reports/4722c07dd9a10c3985ae432a/verifications -u 83ebeabdec09f6670863766f792ead24d61fe3f9:

EXAMPLE PAYLOAD

  {
    "data": [
      {
        "id": "db313e73383710d4fa2f18fd",
        "object": "verification",
        "uri": "https://api.checkr.com/v1/reports/4722c07dd9a10c3985ae432/verifications/db313e73383710d4fa2f18fd",
        "created_at": "2014-01-18T12:34:00Z",
        "completed_at": null,
        "verification_type": "id",
        "verification_url": "http://verifications.checkr.com/db313e73383710d4fa2f18fd"
      }
    ],
    "object": "list",
    "count": 1
  }
 

Adverse item

Represents an Adverse item.

Attributes

id: string
object: string
'adverse_item'
text: string
description of adverse item



EXAMPLE RESOURCE

{
  "id": "57ed4ce3057e0b002adc6d93",
  "object": "adverse_item",
  "text": "License status: Suspended"
}

List existing Adverse items

This request is used to retrieve existing Adverse items.

Note: Report must be in a consider status and cannot have any existing Adverse actions that have not been canceled.

Parameters

report_id: string required

Returns a list of Adverse items for a report.

DEFINITION

GET https://api.checkr.com/v1/reports/:report_id/adverse_items

EXAMPLE REQUEST

$ curl -X GET https://api.checkr.com/v1/reports/b861a56db1b1b89692dd6118/adverse_items -u 83ebeabdec09f6670863766f792ead24d61fe3f9:

EXAMPLE PAYLOAD

{
  "data": [
    {
      "id": "57ed4ce3057e0b002adc6d90",
      "object": "adverse_item",
      "text": "CHARGE: DELIVER COCAINE (STATUTE: 90-95(A)(1)) (DISPOSITION: DISMISSAL W/O LEAVE)"
    },
    {
      "id": "57ed4ce3057e0b002adc6d91",
      "object": "adverse_item",
      "text": "CHARGE: RESISTING PUBLIC OFFICER (STATUTE: 14-223) (DISPOSITION: DISMISSAL W/O LEAVE)"
    }
  ],
  "object": "list",
  "count": 2
}
 

Adverse action

Represents an Adverse action.

Attributes

id: string
object: string
'adverse_action'
uri: string
uri of the resource
created_at: timestamp
iso 8601 format
status: string
values: 'pending', 'complete', 'dispute', 'canceled'
report_id: string
id of the report
post_notice_scheduled_at timestamp
iso 8601 format
post_notice_ready_at timestamp
iso 8601 format
time after which the post notice can be sent
7 days after 'created_at'
canceled_at timestamp
iso 8601 format
adverse_items array of hashes
array of adverse items



EXAMPLE RESOURCE

{
  "id": "57ed51e57619e8002a6683f2",
  "object": "adverse_action",
  "uri": "/v1/adverse_actions/57ed51e57619e8002a6683f2",
  "created_at": "2016-09-29T17:39:49Z",
  "status": "pending",
  "report_id": "b861a56db1b1b89692dd6118",
  "post_notice_scheduled_at": "2016-10-07T12:34:00Z",
  "post_notice_ready_at": "2016-10-06T17:39:48Z",
  "canceled_at": null,
  "adverse_items": [
    {
      "id": "57ed4ce3057e0b002adc6d90",
      "object": "adverse_item",
      "text": "CHARGE: DELIVER COCAINE (STATUTE: 90-95(A)(1)) (DISPOSITION: DISMISSAL W/O LEAVE)"
    },
    {
      "id": "57ed4ce3057e0b002adc6d91",
      "object": "adverse_item",
      "text": "CHARGE: RESISTING PUBLIC OFFICER (STATUTE: 14-223) (DISPOSITION: DISMISSAL W/O LEAVE)"
    }
  ]
}

Create a new Adverse action

This request is used to create a new Adverse action.

Note: Report must be in a consider status and cannot have any existing Adverse actions that have not been canceled.

Parameters

post_notice_scheduled_at: timestamp optional
format: iso 8601
default value: 7 days after creation
adverse_item_ids: array[string] required
ids of adverse items selected

Returns a representation of the Adverse action.

DEFINITION

POST https://api.checkr.com/v1/reports/:id/adverse_actions

EXAMPLE REQUEST

$ curl -X POST https://api.checkr.com/v1/reports/b861a56db1b1b89692dd6118/adverse_actions \
        -u 83ebeabdec09f6670863766f792ead24d61fe3f9: \
        -d post_notice_scheduled_at=2016-10-07T12:34:00Z \
        -d 'adverse_item_ids[]=57ed4ce3057e0b002adc6d90&adverse_item_ids[]=57ed4ce3057e0b002adc6d91'

Retrieve an existing Adverse action

This request is used to retrieve existing Adverse actions.

Parameters

id: string required

Returns a representation of the Adverse action.

DEFINITION

GET https://api.checkr.com/v1/adverse_actions/:id

EXAMPLE REQUEST

$ curl -X GET https://api.checkr.com/v1/adverse_actions/57ed51e57619e8002a6683f2 -u 83ebeabdec09f6670863766f792ead24d61fe3f9:

List existing Adverse actions

This request is used to list existing Adverse actions.

Parameters

status: string
filter adverse actions by status
created_after: date
format: YYYY-MM-DD
filter adverse actions created after this timestamp
created_before: date
format: YYYY-MM-DD
filter adverse actions created before this timestamp

Returns a list of paginated Adverse actions matching the filter(s).

DEFINITION

GET https://api.checkr.com/v1/adverse_actions

EXAMPLE REQUEST

$ curl -X GET https://api.checkr.com/v1/adverse_actions -u 83ebeabdec09f6670863766f792ead24d61fe3f9:

EXAMPLE PAYLOAD

{
  "data": [
    {
      "id": "e44aa283528e6fdaa9542194",
      "object": "adverse_action",
      "uri": "/v1/adverse_actions/e44aa283528e6fde34542194",
      "created_at": "2014-01-18T12:34:00Z",
      "status": "pending",
      "post_notice_scheduled_at": "2014-01-18T12:34:00Z",
      "post_notice_ready_at": "2015-02-25T12:34:00Z",
      "report_id": "823a780091b24d44e67702a6a3",
      "canceled_at": null,
      "adverse_items": [
        {
          "id": "57d9cda7f7b5e4007d03c84f",
          "object": "adverse_item",
          "text": "License status: Expired"
        }
      ]
    },
    {
      "id": "57ed51e57619e8002a6683f2",
      "object": "adverse_action",
      "uri": "/v1/adverse_actions/57ed51e57619e8002a6683f2",
      "created_at": "2016-09-29T17:39:49Z",
      "status": "pending",
      "post_notice_scheduled_at": "2016-10-07T12:34:00Z",
      "post_notice_ready_at": "2016-10-06T17:39:48Z",
      "report_id": "b861a56db1b1b89692dd6118",
      "canceled_at": null,
      "adverse_items": [
        {
          "id": "57ed4ce3057e0b002adc6d90",
          "object": "adverse_item",
          "text": "CHARGE: DELIVER COCAINE (STATUTE: 90-95(A)(1)) (DISPOSITION: DISMISSAL W/O LEAVE)"
        },
        {
          "id": "57ed4ce3057e0b002adc6d91",
          "object": "adverse_item",
          "text": "CHARGE: RESISTING PUBLIC OFFICER (STATUTE: 14-223) (DISPOSITION: DISMISSAL W/O LEAVE)"
        }
      ]
    }
  ],
  "object": "list",
  "count": 2
}

Cancel an existing Adverse action

This request is used to cancel an existing Adverse action.

Parameters

id: string required

Returns a representation of the Adverse action.

DEFINITION

DELETE https://api.checkr.com/v1/adverse_actions/:id

EXAMPLE REQUEST

$ curl -X DELETE https://api.checkr.com/v1/adverse_actions/e44aa283528e6fdaa9542194 \
        -u 83ebeabdec09f6670863766f792ead24d61fe3f9:

Testing Adverse actions

Use your test API key to make requests to the endpoint. A test Adverse action will be created and returned, but will not actually send any notices. You will need to provide the Report ID of a test Report, which you can create by using your test API key when creating a Report. Use the test Report ID to retrieve Adverse item IDs, which you also need to create a test Adverse action.

 

Subscription

Represents a background check subscription. A background report with the package specified will run at every interval.

Attributes

id: string
object: string
'subscription'
uri: string
uri of the resource
status: string
values: 'active', 'inactive'
created_at: timestamp
iso 8601 format
canceled_at: timestamp
iso 8601 format
package: string
values: 'tasker_standard', 'tasker_pro', 'driver_standard', 'driver_pro'
interval_count: integer
The number of intervals between each recurrent background check
interval_unit: string
values: 'day', 'week', 'month', 'year'
start_date: date
format: YYYY-MM-DD
candidate_id: string
id of the candidate screened



EXAMPLE RESOURCE

  {
    "id": "4722c07dd9a10c3985ae432a",
    "object": "subscription",
    "uri": "/v1/subscriptions/4722c07dd9a10c3985ae432a",
    "status": "active",
    "created_at": "2014-01-18T12:34:00Z",
    "canceled_at": null,
    "package": "driver_pro",
    "interval_count": 1,
    "interval_unit": "month",
    "start_date": "2014-06-10",
    "candidate_id": "e44aa283528e6fde7d542194"
  }

Retrieve an existing Subscription

This request is used to retrieve existing Subscriptions.

Parameters

id: string required

Returns a representation of the Subscription.

DEFINITION

GET https://api.checkr.com/v1/subscriptions/:id

EXAMPLE REQUEST

$ curl -X GET https://api.checkr.com/v1/subscriptions/4722c07dd9a10c3985ae432a -u 83ebeabdec09f6670863766f792ead24d61fe3f9:

Create a new Subscription

This request is used to create a new Subscription.

Parameters

package: string required
candidate_id: string required
start_date: date required
format: YYYY-MM-DD
interval_count: integer
The number of intervals between each recurrent background check
interval_unit: string
values: 'day', 'week', 'month', 'year'

Returns a representation of the Subscription.

DEFINITION

POST https://api.checkr.com/v1/subscriptions

EXAMPLE REQUEST

$ curl -X POST https://api.checkr.com/v1/subscriptions \
        -u 83ebeabdec09f6670863766f792ead24d61fe3f9: \
        -d package=driver_pro \
        -d start_date=2017-02-10 \
        -d interval_unit=month \
        -d interval_count=1 \
        -d candidate_id=e44aa283528e6fde7d542194

Cancel an existing Subscription

This request is used to cancel an existing Subscription.

Parameters

id: string required

Returns a representation of the Subscription.

DEFINITION

DELETE https://api.checkr.com/v1/subscriptions/:id

EXAMPLE REQUEST

$ curl -X DELETE https://api.checkr.com/v1/subscriptions/4722c07dd9a10c3985ae432a \
        -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
 

Geo

Represents a candidate geography.

Attributes

id: string
object: string
'geo'
uri: string
uri of the resource
created_at: timestamp
iso 8601 format
name: string
name of the geo
state: string
format: ST
deleted_at: timestamp
iso 8601 format



EXAMPLE RESOURCE

  {
    "id": "e44aa283528e6fde7d542194",
    "object": "geo",
    "uri": "/v1/geos/e44aa283528e6fde7d542194",
    "created_at": "2015-01-18T12:34:00Z",
    "name": "San Francisco",
    "state": "CA",
    "deleted_at": null
  }

Retrieve an existing Geo

This request is used to retrieve an existing Geo.

Parameters

id: string required

Returns a representation of the Geo.

DEFINITION

GET https://api.checkr.com/v1/geos/:id

EXAMPLE REQUEST

$ curl -X GET https://api.checkr.com/v1/geos/e44aa283528e6fde7d542194 -u 83ebeabdec09f6670863766f792ead24d61fe3f9:

Create a new Geo

This request is used to create a new Geo.

Parameters

name: string required
state: string required
format: ST

Returns a representation of the Geo.

DEFINITION

POST https://api.checkr.com/v1/geos

EXAMPLE REQUEST

$ curl -X POST https://api.checkr.com/v1/geos \
        -u 83ebeabdec09f6670863766f792ead24d61fe3f9: \
        -d name=San+Francisco \
        -d state=CA

Delete an existing Geo

This request is used to delete an existing Geo.

Parameters

id: string required

Returns a representation of the Geo.

DEFINITION

DELETE https://api.checkr.com/v1/geos/:id

EXAMPLE REQUEST

$ curl -X DELETE https://api.checkr.com/v1/geos/b719804dc15c655f8529a2f2 \
        -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
 

Program

Represents a division of an Account. Programs are typically used to identify clients, cost centers, or departments. A Program has many Geos and has many Packages.

Attributes

id: string
object: string
'program'
name: string
name of the program
created_at: timestamp
iso 8601 format
deleted_at: timestamp
iso 8601 format
package_ids: array
list of associated packages
geo_ids: array
list of associated geos



EXAMPLE RESOURCE

  {
    "id": "e44aa283528e6fde7d542194",
    "object": "program",
    "name": "Program A",
    "created_at": "2015-01-18T12:34:00Z",
    "deleted_at": null,
    "package_ids": [
        "539fdcf335644a0ef4000003",
        "532e71cfe88a1d4e8d000005",
    ],
    "geo_ids": [
        "539fdcf335644a0ef4000001",
        "532e71cfe88a1d4e8d00000c",
    ]
  }

Retrieve an existing program

This request is used to retrieve an existing program.

Parameters

id: string required

Returns a representation of the Program.

DEFINITION

GET https://api.checkr.com/v1/programs/:id

EXAMPLE REQUEST

$ curl -X GET https://api.checkr.com/v1/programs/e44aa283528e6fde7d542194 -u 83ebeabdec09f6670863766f792ead24d61fe3f9:

List existing Programs

This request is used to list existing Programs.

Parameters

name: string
filter programs by name

Returns a paginated list of Programs matching the filter(s).

DEFINITION

GET https://api.checkr.com/v1/programs

EXAMPLE REQUEST

$ curl -X GET https://api.checkr.com/v1/programs -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
 

SSN trace

Represents a list of all the addresses, name aliases and phone numbers of the candidate that have been recorded by credit agencies in the last 7 years. It is attached to a report.

Attributes

id: string
object: string
'ssn_trace'
uri: string
uri of the resource
status: string
values: 'pending', 'clear', 'consider'
created_at: timestamp
iso 8601 format
completed_at: timestamp
iso 8601 format
turnaround_time: integer
seconds
ssn: string
addresses: array
list of address objects
aliases: array
list of name objects



EXAMPLE RESOURCE

{
  "id": "539fd88c101897f7cd000001",
  "object": "ssn_trace",
  "uri": "/v1/ssn_traces/539fd88c101897f7cd000001",
  "status": "clear",
  "created_at": "2014-01-18T12:34:00Z",
  "completed_at": "2014-01-18T12:35:30Z",
  "turnaround_time": 90,
  "ssn": "XXX-XX-4645",
  "addresses": [
    {
      "street": "123 S Folsom St",
      "unit": "Apt 54B",
      "city": "San Francisco",
      "state": "CA",
      "zipcode": "94110",
      "county": "SAN FRANCISCO",
      "from_date": "2010-05-01",
      "to_date": "2014-06-01"
    },
    {
      "street": "1230 5th Avenue",
      "unit": null,
      "city": "New York",
      "state": "NY",
      "zipcode": "1005",
      "county": "NEW YORK",
      "from_date": "2007-07-01",
      "to_date": "2010-05-01"
    }
  ],
  "aliases": [
    {
      "first_name": "Jack",
      "middle_name": "B",
      "last_name": "Fieldman"
    }
  ]
}

Retrieve an existing SSN trace

This request is used to retrieve existing SSN traces.

Parameters

id: string required

Returns a representation of the SSN trace.

DEFINITION

GET https://api.checkr.com/v1/ssn_traces/:id

EXAMPLE REQUEST

$ curl -X GET https://api.checkr.com/v1/ssn_traces/539fd88c101897f7cd000001 -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
 

Sex offender search

Represents an instant multi-state sex offender registry search.

Attributes

id: string
object: string
'sex_offender_search'
uri: string
uri of the resource
status: string
values: 'pending', 'clear', 'consider'
created_at: timestamp
iso 8601 format
completed_at: timestamp
iso 8601 format
turnaround_time: integer
seconds
records: array
list of records



EXAMPLE RESOURCE

{
  "id": "539fd88c101897f7cd000008",
  "object": "sex_offender_search",
  "uri": "/v1/sex_offender_searches/539fd88c101897f7cd000008",
  "status": "consider",
  "created_at": "2014-01-18T12:34:00Z",
  "completed_at": "2014-01-18T12:35:30Z",
  "turnaround_time": 90,
  "records": [
    {
      "registry": "California",
      "full_name": "John Alfred Smith",
      "age": 44,
      "dob": "1971-04-11",
      "address": {
        "street": "123 S Folsom St",
        "city": "San Francisco",
        "state": "CA",
        "zipcode": "94110"
      },
      "race": "white",
      "gender": "male",
      "eye_color": "brown",
      "hair_color": "brown",
      "height": 70,
      "weight": 175,
      "registration_start": "2011-02-12",
      "registration_end": "life registration"
    }
  ]
}

Retrieve an existing sex offender search

This request is used to retrieve existing sex offender searches.

Parameters

id: string required

Returns a representation of the sex offender search.

DEFINITION

GET https://api.checkr.com/v1/sex_offender_searches/:id

EXAMPLE REQUEST

$ curl -X GET https://api.checkr.com/v1/sex_offender_searches/539fd88c101897f7cd000008 -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
 

Global watchlist search

Represents an instant global watchlist search.

Attributes

id: string
object: string
'global_watchlist_search'
uri: string
uri of the resource
status: string
values: 'pending', 'clear', 'consider'
created_at: timestamp
iso 8601 format
completed_at: timestamp
iso 8601 format
turnaround_time: integer
seconds
records: array
list of records



EXAMPLE RESOURCE

{
  "id": "539fd88c101897f7cd000008",
  "object": "global_watchlist_search",
  "uri": "/v1/global_watchlist_searches/539fd88c101897f7cd000008",
  "status": "consider",
  "created_at": "2014-01-18T12:34:00Z",
  "completed_at": "2014-01-18T12:35:30Z",
  "turnaround_time": 90,
  "records": [
    {
      "case_number": "24323-DA",
      "file_date": null,
      "arresting_agency": "DEA Boston Division",
      "court_jurisdiction": null,
      "court_of_record": null,
      "dob": "1970-01-22",
      "full_name": "John Alfred Smith",
      "charges": [
        {
          "charge": "RICO murder",
          "charge_type": null,
          "charge_id": null,
          "classification": "Felony",
          "deposition": null,
          "defendant": null,
          "plaintiff": null,
          "sentence": "Active Punishment Minimum: 10Y",
          "disposition": "Guilty",
          "probation_status": null,
          "offense_date": "2011-04-22",
          "deposition_date": "2014-05-27",
          "arrest_date": null,
          "charge_date": null,
          "sentence_date": null,
          "disposition_date": "2011-06-02"
        }
      ]
    }
  ]
}

Retrieve an existing global watchlist search

This request is used to retrieve existing global watchlist searches.

Parameters

id: string required

Returns a representation of the global watchlist search.

DEFINITION

GET https://api.checkr.com/v1/global_watchlist_searches/:id

EXAMPLE REQUEST

$ curl -X GET https://api.checkr.com/v1/global_watchlist_searches/539fd88c101897f7cd000008 -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
 

National criminal search

Represents an instant multi-state search of criminal records.

Attributes

id: string
object: string
'national_criminal_search'
uri: string
uri of the resource
status: string
values: 'pending', 'clear', 'consider'
created_at: timestamp
iso 8601 format
completed_at: timestamp
iso 8601 format
turnaround_time: integer
seconds
records: array
list of records



EXAMPLE RESOURCE

{
  "id": "539fd88c101897f7cd000006",
  "object": "national_criminal_search",
  "uri": "/v1/national_criminal_searches/539fd88c101897f7cd000006",
  "status": "clear",
  "created_at": "2014-01-18T12:34:00Z",
  "completed_at": "2014-01-18T12:35:30Z",
  "turnaround_time": 90,
  "records": [
    {
      "case_number": "24323-DA",
      "file_date": null,
      "arresting_agency": null,
      "court_jurisdiction": null,
      "court_of_record": null,
      "dob": "1970-01-22",
      "full_name": "John Alfred Smith",
      "charges": []
    }
  ]
}

Retrieve an existing national criminal search

This request is used to retrieve existing national criminal searches.

Parameters

id: string required

Returns a representation of the national criminal search.

DEFINITION

GET https://api.checkr.com/v1/national_criminal_searches/:id

EXAMPLE REQUEST

$ curl -X GET https://api.checkr.com/v1/national_criminal_searches/539fd88c101897f7cd000006 -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
 

County criminal search

Represents a search of criminal records in a specific county.

Attributes

id: string
object: string
'county_criminal_search'
uri: string
uri of the resource
status: string
values: 'pending', 'clear', 'consider'
created_at: timestamp
iso 8601 format
completed_at: timestamp
iso 8601 format
turnaround_time: integer
seconds
county: string
state: string
records: array
list of records



EXAMPLE RESOURCE

{
  "id": "539fdcf335644a0ef4000001",
  "object": "county_criminal_search",
  "uri": "/v1/county_criminal_searches/539fdcf335644a0ef4000001",
  "status": "consider",
  "created_at": "2014-01-18T12:34:00Z",
  "completed_at": "2014-01-18T12:35:30Z",
  "turnaround_time": 100800,
  "county": "SAN FRANCISCO",
  "state": "CA",
  "records": [
    {
      "case_number": "24323-DA",
      "file_date": "2010-02-18",
      "arresting_agency": "San Francisco Police Department",
      "court_jurisdiction": "San Francisco",
      "court_of_record": null,
      "dob": "1970-01-22",
      "full_name": "John Alfred Smith",
      "charges": [
        {
          "charge": "Sell Cocaine",
          "charge_type": null,
          "charge_id": null,
          "classification": "Felony",
          "deposition": null,
          "defendant": "John Alfred Smith",
          "plaintiff": null,
          "sentence": "Active Punishment Minimum: 10M",
          "disposition": "Guilty",
          "probation_status": null,
          "offense_date": "2011-04-22",
          "deposition_date": "2014-05-27",
          "arrest_date": "2011-04-22",
          "charge_date": null,
          "sentence_date": "2011-06-02",
          "disposition_date": "2011-06-02"
        }
      ]
    }
  ]
}

Retrieve an existing county criminal search

This request is used to retrieve existing county criminal searches.

Parameters

id: string required

Returns a representation of the county criminal search.

DEFINITION

GET https://api.checkr.com/v1/county_criminal_searches/:id

EXAMPLE REQUEST

$ curl -X GET https://api.checkr.com/v1/county_criminal_searches/539fdcf335644a0ef4000001 -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
 

State criminal search

Represents a search of criminal records in a specific state.

Attributes

id: string
object: string
'state_criminal_search'
uri: string
uri of the resource
status: string
values: 'pending', 'clear', 'consider'
created_at: timestamp
iso 8601 format
completed_at: timestamp
iso 8601 format
turnaround_time: integer
seconds
state: string
records: array
list of records



EXAMPLE RESOURCE

{
  "id": "539fdcf335644a0ef4000001",
  "object": "state_criminal_search",
  "uri": "/v1/state_criminal_searches/539fdcf335644a0ef4000001",
  "status": "consider",
  "created_at": "2014-01-18T12:34:00Z",
  "completed_at": "2014-01-18T12:35:30Z",
  "turnaround_time": 100800,
  "state": "CA",
  "records": [
    {
      "case_number": "24323-DA",
      "file_date": "2010-02-18",
      "arresting_agency": "San Francisco Police Department",
      "court_jurisdiction": "San Francisco",
      "court_of_record": null,
      "dob": "1970-01-22",
      "full_name": "John Alfred Smith",
      "charges": [
        {
          "charge": "Sell Cocaine",
          "charge_type": null,
          "charge_id": null,
          "classification": "Felony",
          "deposition": null,
          "defendant": "John Alfred Smith",
          "plaintiff": null,
          "sentence": "Active Punishment Minimum: 10M",
          "disposition": "Guilty",
          "probation_status": null,
          "offense_date": "2011-04-22",
          "deposition_date": "2014-05-27",
          "arrest_date": "2011-04-22",
          "charge_date": null,
          "sentence_date": "2011-06-02",
          "disposition_date": "2011-06-02"
        }
      ]
    }
  ]
}

Retrieve an existing state criminal search

This request is used to retrieve existing state criminal searches.

Parameters

id: string required

Returns a representation of the state criminal search.

DEFINITION

GET https://api.checkr.com/v1/state_criminal_searches/:id

EXAMPLE REQUEST

$ curl -X GET https://api.checkr.com/v1/state_criminal_searches/539fdcf335644a0ef4000001 -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
 

Motor vehicle report

Represents a report of the candidate's driving history, as reported from the state Department of Motor Vehicles. It is attached to a Report.

Attributes

id: string
object: string
'motor_vehicle_report'
uri: string
uri of the resource
status: string
values: 'pending', 'clear', 'consider'
created_at: timestamp
iso 8601 format
completed_at: timestamp
iso 8601 format
turnaround_time: integer
seconds
full_name: string
license_number: string
license_state: string
previous_license_number: string
previous_license_state: string
license_status: string
license_type: string
license_class: string
expiration_date: string
format: YYYY-MM-DD
issued_date: string
format: YYYY-MM-DD
first_issued_date: string
format: YYYY-MM-DD
inferred_issued_date: string
format: YYYY-MM-DD
restrictions: array
list of strings
accidents: array
list of accident records
violations: array
list of violation records



EXAMPLE RESOURCE

{
  "id": "539fd88c101897f7cd000007",
  "object": "motor_vehicle_report",
  "uri": "/v1/motor_vehicle_reports/539fd88c101897f7cd000007",
  "status": "consider",
  "created_at": "2014-01-18T12:34:00Z",
  "completed_at": "2014-01-18T12:35:30Z",
  "turnaround_time": 90,
  "full_name": "John Alfred Smith",
  "license_number": "F2111132",
  "license_state": "CA",
  "license_status": "valid",
  "license_type": "non-commercial",
  "license_class": "C",
  "expiration_date": "2016-07-24",
  "issued_date": "2006-12-03",
  "first_issued_date": "2000-01-14",
  "inferred_issued_date": null,
  "restrictions": [],
  "accidents": [
    {
      "accident_date": "2009-04-12",
      "description": "property damage",
      "city": null,
      "county": "SAN FRANCISCO",
      "state": null,
      "order_number": "33-435932",
      "points": null,
      "vehicle_speed": null,
      "reinstatement_date": null,
      "action_taken": "police report filed",
      "ticket_number": null,
      "enforcing_agency": "San Francisco PD",
      "jurisdiction": null,
      "severity": null,
      "violation_number": null,
      "license_plate": "6UM6938",
      "fine_amount": null,
      "state_code": null,
      "acd_code": null,
      "injury_accident": false,
      "fatality_accident": false,
      "fatality_count": 0,
      "injury_count": 0,
      "vehicles_involved_count": 1,
      "report_number": null,
      "policy_number": null
    }
  ],
  "violations": [
    {
      "type": "conviction",
      "issued_date": "2011-11-14",
      "conviction_date": "2010-04-11",
      "description": "speeding 15-19 mph",
      "points": 0,
      "city": null,
      "county": "SANTA CLARA",
      "state": "California",
      "ticket_number": "2D55555",
      "disposition": null,
      "category": null,
      "court_name": null,
      "acd_code": null,
      "state_code": null,
      "docket": null
    }
  ]
}

Retrieve an existing Motor Vehicle Report

This request is used to retrieve existing Motor Vehicle Reports.

Parameters

id: string required

Returns a representation of the Motor Vehicle Report.

DEFINITION

GET https://api.checkr.com/v1/motor_vehicle_reports/:id

EXAMPLE REQUEST

$ curl -X GET https://api.checkr.com/v1/motor_vehicle_reports/539fd88c101897f7cd000007 -u 83ebeabdec09f6670863766f792ead24d61fe3f9: