Skip to content
/
Retrieve an existing Cand...

Retrieve an existing Candidate

Request

Retrieves an existing Candidate.

Security
basic_auth
Path
idstringrequired

The Candidate's ID.

Query
includestring

Comma delimited string specifying the resources to be embedded in the returned Candidate object. See Embedding Resources.

Enum:"reports""geos"
Example:include=reports,geos
curl -i -X GET \
  -u '<username>:<password>' \
  'https://docs.checkr.com/_mock/apis/openapi/candidates/{id}?include=reports%2Cgeos'

Responses

Candidate details

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)

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" }

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": {}
}
© Checkr, Inc.