Candidates

Candidates represent people who have applied for positions within your company, and have agreed to a background check. Use the Candidate object to collect all Personally Identifiable Information (PII) for a candidate, and all relevant Checkr information, including any generated Reports, or attached Geos.

Operations

Create a new Candidate

Request

Creates a new Candidate resource.

Required attributes

The Candidate resource’s required attributes vary depending on its intended use. If this resource is to be used in conjunction with the Invitations API (in which the invitation apply form collects the Candidate's personal information), the only strictly required Candidate attribute is email.

If this resource is to be used to generate any other report type, other personal information is also required.

Attributes required to generate a Report include:

first_name
middle_name or no_middle_name
last_name
dob

Attributes required to generate a Report with a criminal check screening:

ssn
zipcode

Attributes required to generate a report with a Motor Vehicle Record (MVR) screening:

driver_license_number
driver_license_state

See Driver License validation in the Reference section for a list of valid input by state.

Attributes recommended to generate a report with an Identity Document Verification screening:

phone (mobile phone number)

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

Checkr's product incorporates SSN field controls designed to not accept SSNs with the following characteristics:

SSNs without exactly 9 numeric characters
SSNs that start with 666 (666-34-3768)
SSNs that start with 9 (967-65-4325)
SSNs that are a single digit (111-11-1111)
SSNs that are sequential digits (123-45-6789)

Security

basic_auth

Bodyapplication/jsonrequired

first_namestring^(?=.*[a-zA-ZªµºÀ-ÖØ-öø-ÿ])[a-zA-Z0-9ªµºÀ-ÖØ-...

Candidate’s first name.

Example:"John"

middle_namestring[a-zA-Z0-9ªµºÀ-ÖØ-öø-ÿ\-'., ]*

Candidate’s middle name. This field is required if no_middle_name is false.

Example:"Alfred"

no_middle_nameboolean

Required if no middle_name is provided. true if the candidate has no middle name.

Default:false

last_namestring[a-zA-Z0-9ªµºÀ-ÖØ-öø-ÿ\-'., ]{2,}

Candidate’s last name.

Example:"Smith"

mother_maiden_namestring[a-zA-Z0-9ªµºÀ-ÖØ-öø-ÿ\-'., ]*

Candidate’s mother’s maiden name.

Example:"Jones"

emailstring, (email)required

Candidate’s email address.

Example:"john.smith@gmail.com"

phonestring or null

Candidate’s phone number.

Example:5555555555

zipcodestring

Candidate’s 5-digit zip code.

Example:90401

dobstring, (date)

Candidate’s date of birth.

Example:"1970-01-22"

ssnstring

Candidate’s Social Security Number. This value will be redacted in all return calls, except for the last four digits.

Example:"XXX-XX-4645"

driver_license_numberstring

Candidate’s driver license number.

Example:"F2111655"

driver_license_statestring

Candidate’s driver license state of issue. Format: ISO 3166-2:US.

Example:"CA"

previous_driver_license_numberstring

Candidate’s previous driver license number.

Example:"F1501739"

previous_driver_license_statestring

State that issued the candidate’s previous driver license. Format: ISO 3166-2:US.

Example:"MD"

copy_requestedboolean

If true, the candidate has asked to receive a copy of their report.

Default:false

postal_addressobject

The candidate postal address is the address Checkr will use to send postal mail to the candidate. Each candidate can be associated with only one postal address.

Example:

{
  "name": "John Alfred Smith",
  "street": "123 Main Street",
  "street2": "APT A",
  "city": "San Francisco",
  "state": "CA",
  "zipcode": "94108"
}

custom_idstring

Client-assigned unique ID for the Candidate. Can be used to map Checkr Candidate IDs to your internal tracking system, and to search for Candidates through both the Dashboard and the API.

Example:"HRIS-27"

geo_idsArray of strings

Array of Geo IDs.

Example:

[
  "79f943e212cce7de21c054a8"
]

metadataobject(Metadata)

Up to 50 customer-defined key-value pairs. Use this parameter to store additional information on your candidate. For example: Use the key to map candidates to job_req_id, application_id, or branch_id. Keys must be 40 characters or less. Values must be 500 characters or less. For example: { "job_req_id": "12345" }

work_locationsArray of objects(WorkLocation)

Required for non-US candidates.

Array of locations described using country, state, and city. When country is not specified defaults to US. State is required for US candidates. Country is required for non-US candidates.

curl -i -X POST \
  -u '<username>:<password>' \
  https://docs.checkr.com/_mock/apis/openapi/candidates \
  -H 'Content-Type: application/json' \
  -d '{
    "first_name": "John",
    "middle_name": "Alfred",
    "no_middle_name": false,
    "last_name": "Smith",
    "mother_maiden_name": "Jones",
    "email": "john.smith@gmail.com",
    "phone": 5555555555,
    "zipcode": 90401,
    "dob": "1970-01-22",
    "ssn": "XXX-XX-4645",
    "driver_license_number": "F2111655",
    "driver_license_state": "CA",
    "previous_driver_license_number": "F1501739",
    "previous_driver_license_state": "MD",
    "copy_requested": false,
    "postal_address": {
      "name": "John Alfred Smith",
      "street": "123 Main Street",
      "street2": "APT A",
      "city": "San Francisco",
      "state": "CA",
      "zipcode": "94108"
    },
    "custom_id": "HRIS-27",
    "geo_ids": [
      "79f943e212cce7de21c054a8"
    ],
    "metadata": {},
    "work_locations": [
      {
        "country": "US",
        "state": "CA",
        "city": "San Francisco"
      }
    ]
  }'

Responses

Candidate was successfully created

Bodyapplication/json

idstring(ResourceId)read-only

ID of the resource.

Example:"e44aa283528e6fde7d542194"

objectstringread-only

Value:"candidate"

uristring(ResourceURI)read-only

URI of the resource.

Example:"/v1/candidates/e44aa283528e6fde7d542194"

first_namestring, non-empty^(?=.*[a-zA-ZªµºÀ-ÖØ-öø-ÿ])[a-zA-Z0-9ªµºÀ-ÖØ-...

Candidate’s first name.

Example:"John"

middle_namestring[a-zA-Z0-9ªµºÀ-ÖØ-öø-ÿ\-'., ]*

Candidate’s middle name. This field is required if no_middle_name is false.

Example:"Alfred"

no_middle_nameboolean

Required if no middle_name is provided. true if the candidate has no middle name.

Default:false

last_namestring, non-empty[a-zA-Z0-9ªµºÀ-ÖØ-öø-ÿ\-'., ]{2,}

Candidate’s last name.

Example:"Smith"

mother_maiden_namestring[a-zA-Z0-9ªµºÀ-ÖØ-öø-ÿ\-'., ]*

Candidate’s mother’s maiden name.

Example:"Jones"

emailstring, (email)

Candidate’s email address.

Example:"john.smith@gmail.com"

phonestring or null

Candidate’s phone number.

Example:5555555555

zipcodestring

Candidate’s 5-digit zip code.

Example:90401

dobstring, (date)

Candidate’s date of birth.

Example:"1970-01-22"

ssnstring

Candidate’s Social Security Number. This value will be redacted in all return calls, except for the last four digits.

Example:"XXX-XX-4645"

driver_license_numberstring

Candidate’s driver license number.

Example:"F2111655"

driver_license_statestring

Candidate’s driver license state of issue. Format: ISO 3166-2:US.

Example:"CA"

previous_driver_license_numberstring

Candidate’s previous driver license number.

Example:"F1501739"

previous_driver_license_statestring

State that issued the candidate’s previous driver license. Format: ISO 3166-2:US.

Example:"MD"

copy_requestedboolean

If true, the candidate has asked to receive a copy of their report.

Default:false

custom_idstring

Client-assigned unique ID for the Candidate. Can be used to map Checkr Candidate IDs to your internal tracking system, and to search for Candidates through both the Dashboard and the API.

report_idsArray of stringsread-only

Array of Report IDs.

Example:

[
  "532e71cfe88a1d4e8d00000d"
]

geo_idsArray of strings

Array of Geo IDs.

Example:

[
  "79f943e212cce7de21c054a8"
]

adjudicationstring

The adjudication for the Candidate’s most recently created Report.

Enum:"engaged""pre_adverse_action""post_adverse_action"

postal_addressobject

Candidate's postal address.

Example:

{
  "name": "John Alfred Smith",
  "street": "123 Main Street",
  "street2": "APT A",
  "city": "San Francisco",
  "state": "CA",
  "zipcode": "94108"
}

metadataobject(Metadata)

Response

{
  "id": "e44aa283528e6fde7d542194",
  "object": "candidate",
  "uri": "/v1/candidates/e44aa283528e6fde7d542194",
  "first_name": "John",
  "middle_name": "Alfred",
  "no_middle_name": false,
  "last_name": "Smith",
  "mother_maiden_name": "Jones",
  "email": "john.smith@gmail.com",
  "phone": 5555555555,
  "zipcode": 90401,
  "dob": "1970-01-22",
  "ssn": "XXX-XX-4645",
  "driver_license_number": "F2111655",
  "driver_license_state": "CA",
  "previous_driver_license_number": "F1501739",
  "previous_driver_license_state": "MD",
  "copy_requested": false,
  "custom_id": "string",
  "report_ids": [
    "532e71cfe88a1d4e8d00000d"
  ],
  "geo_ids": [
    "79f943e212cce7de21c054a8"
  ],
  "adjudication": "engaged",
  "postal_address": {
    "name": "John Alfred Smith",
    "street": "123 Main Street",
    "street2": "APT A",
    "city": "San Francisco",
    "state": "CA",
    "zipcode": "94108"
  },
  "metadata": {}
}

Candidates

Create a new Candidate

Request

Required attributes

Responses

Was this page helpful?