Skip to content

Create check

Request

Create a new check.

Profile vs inline PII: Submit either a profile_id or inline PII/address fields—not both. Combining profile_id with name fields, address, addresses, or other PII returns 400 Bad Request (validation_error: "request must only contain a profile_id, or other fields"). Empty address: {} or addresses: [] count as supplied address parameters and cannot be paired with profile_id.

Security
get-bearer-token-using-oauth2
Query
include[]Array of strings

Request optional response fields. Repeat the parameter for multiple values.

Items Enum ValueDescription
profile

Embeds the full profile object in place of profile_id.

rulesets_applied

Embeds the rulesets applied when filtering this check's results.

Examples:
Single value
include[]=["profile"]
Multiple values
include[]=["profile","rulesets_applied"]
Bodyapplication/jsonrequired

The request body for creating a new check.

Use either inline PII/address fields or profile_id—not both. See the POST /checks operation for details.

One of:

Exactly one name format must be provided: either full_name alone, or first_name and last_name (optionally with middle_name). Combining full_name with a name-part field (first_name, middle_name, or last_name) is rejected. no_middle_name may be sent alongside either format.

middle_namestring

middle name(s)

Example:"Mary Louise"
no_middle_nameboolean(no_middle_name)

Set to true to declare that the subject does not have a middle name.

Mutually exclusive with a non-empty middle_name: the API rejects requests that supply both a present middle_name and no_middle_name: true. An empty or null middle_name with no_middle_name: true is allowed. A non-empty middle_name may be supplied with no_middle_name: false.

Allowed with full_name: full_name and no_middle_name may be sent together. That is not the same as supplying middle_name — when the flag is true, parsing stores only a first name and surname, and any token the parser would have treated as a middle name is folded into the last name (for example full_name: "John Quincy Doe" becomes first name John and last name Quincy Doe, with middle_name empty).

Setting this to true clears a middle name already stored on a referenced profile. Supplying a non-empty middle_name without this field sets no_middle_name to false. When true, products that perform criminal-record identity matching exclude records with a middle name, narrowing matches to subjects with no middle name on record. When supplied with profile_id, the value is persisted to the referenced profile (same account-scoped profile the check is created against). Leave as false (or omit) if unsure.

Default:false
check_typestring(check_type)
Enum:"instant_criminal""sex_offender_registry"
input_typestring(input_type)

The type of input being provided for the search. Can be either a person's information or an address.

Default:"person"
Enum:"person""address"
first_namestring

first name (given name). Do not include prefixes, like "Ms." or "Dr."

Example:"Jane"
last_namestring

last name (surname). Do not include suffixes, like "Jr." or "2nd".

Example:"O'Donnell-Van Helsing"
full_namestring

Either send the full name, or first, middle (optional), and last names, but not both. If you send a full name, we will attempt to parse it into first name, middle name(s) and last name, and then use those for the check. With no_middle_name: true, any parsed middle token is folded into the last name instead of being stored as a middle name. If you already know the first and last names, we suggest sending them. The parser will attempt to remove prefixes and suffixes, and handles several different formats of name, but we cannot guarantee it will parse the name in the manner you expect.

Example:"O'Donnell-Van Helsing, Dr. Jane Mary Louise, MD"
dobstring, = 8 characters(date_string_complete)\d{8}

Date of birth in the form YYYYMMDD. Must be a valid date and cannot be in the future. If invalid, the API returns a 400 with a validation_error pointing to /dob.

Example:"19950401"
ssnstring(ssn_string)^\d{3}-?\d{2}-?\d{4}$

Social Security Number used for additional identity verification and record matching

Example:"123-45-6789"
phonestring(phone_string)^\+[1-9]\d{1,14}$

A phone number in the form +[country code][number including area code]. (E.164 format). Please note that U.S. phone numbers have a country code of "1" so all U.S. phone numbers ought to start with "+1". A U.S. number supplied in national format (for example "(415) 555-0123") is normalized to E.164 on write. If the value cannot be parsed as a valid phone number, the API returns a 400 with a validation_error.

Example:"+14155552671"
addressesArray of objects, [ 1 .. 30 ] items(addresses)

An array of addresses to search for criminal records. When provided, records will be matched against any of the addresses in the array. Index 0 is the primary address.

On inline create, addresses are saved to the new profile.

Example:
[
  {
    "street": "456 Oak Ave",
    "city": "Los Angeles",
    "state": "CA",
    "zip_code": "90001"
  },
  {
    "street": "789 Pine Blvd",
    "city": "San Diego",
    "state": "CA",
    "zip_code": "92101"
  }
]
ruleset_idstring, (uuid)(ruleset_id)

Identifier of an existing ruleset containing filtering rules. To set up account rulesets, please reach out to your Checkr Account Executive or Customer Success representative to set up the configuration.

Example:"d16e88e6-aacc-4c42-9cd2-58a93dc9d8af"
ruleset_idsArray of strings(ruleset_ids)

A list of ruleset identifiers to apply. When both ruleset_id and ruleset_ids are provided, they are merged and de-duplicated before applying.

reference_idstring(reference_id)^[a-zA-Z0-9_-]{1,64}$

A reference identifier for linking related records. Limited to 64 alphanumeric characters, underscores, and hyphens.

Example:"ref-123"
source_statesArray of strings(source_states)

An array of state abbreviations. Only records which come from a given source state are included in the results. Note that some sources are not tagged as coming from a single source state, so records from those sources will always be included. Sex offender registry records and most watchlist records are not tagged with a source state, and so will appear in the results regardless of this flag.

order_bystring(order_by)

Specifies the field to sort the results by. Currently only supported for 'photo_urls'.

Value:"photo_urls"
Example:"photo_urls"
allow_duplicate_criminal_recordsboolean(check_request_allow_duplicate_criminal_records)

Multi-source deduplication runs by default for instant criminal, targeted instant criminal, sex offender registry, and criminal_check (via POST /v1/criminal_checks). It may merge or suppress duplicate rows across data providers.

  • false or omit: apply deduplication for this check.
  • true: skip multi-source deduplication; results may include duplicate source rows in storage and in API responses (and webhooks for criminal_check).

Create-time only: send on create; not a query parameter on GET.

Default:false
curl -i -X POST \
  'https://api.checkrtrust.com/v1/checks?include%5B%5D=profile' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "first_name": "JOHN",
    "last_name": "SMITH",
    "dob": "19900101",
    "ssn": "123-45-6789",
    "phone": "+14155552671",
    "addresses": [
      {
        "street": "456 Oak Ave",
        "city": "Los Angeles",
        "state": "CA",
        "zip_code": "90001"
      },
      {
        "street": "789 Pine Blvd",
        "city": "San Diego",
        "state": "CA",
        "zip_code": "92101"
      }
    ]
  }'

Responses

Created. When the product has usage limits configured, the response includes X-RateLimit-Limit, X-RateLimit-Remaining, and optionally X-RateLimit-Expires.

Bodyapplication/json
One of:
idstring, (uuid)(uuid)

A universally unique identifier (UUID) in standard format.

Example:"2b8313e8-4efd-45a1-b578-952b8313e890"
created_atstring, (date-time)(datetime)

An ISO 8601 formatted date-time string.

Example:"2020-01-01T00:00:00Z"
completed_atdatetime (string) or null
One of:

An ISO 8601 formatted date-time string.

string (date-time)(datetime)
resultsArray of objects(record)

Array of criminal records. When no records are found, this is an empty array.

Confidence scoring: Each record's cases[] entries may include identity_match_confidence_level, summarizing identity-match confidence for that case. See the case schema and the Instant Criminal Checks tag description.

check_typestring(check_type)
Enum:"instant_criminal""sex_offender_registry"
reference_idstring(reference_id)^[a-zA-Z0-9_-]{1,64}$

A reference identifier for linking related records. Limited to 64 alphanumeric characters, underscores, and hyphens.

Example:"ref-123"
run_notesArray of strings

An unstructured array of human-readable notes about this particular check. May contain notes about how input was parsed, or other information about results. Not intended to be parsed by computer, as these notes are not guaranteed to be in any given format.

Example:
[
  "changed last_name from 'Smith Jr' to 'Smith'"
]
results_foundboolean

Present only when include[]=results_found is requested; omitted otherwise. When present, the results array is omitted.

rulesets_appliedArray of objects(ruleset_applied)

Present only when include[]=rulesets_applied is requested; omitted otherwise.

profile_idstring, (uuid)(profile_id)

Identifier of an existing profile containing search criteria.

Example:"2b8313e8-4efd-45a1-b578-952b8313e890"
Response
{
  "profile_id": "2b8313e8-4efd-45a1-b578-952b8313e890"
}