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.

One of:

Provide first_name and last_name (without full_name).

object(name-parts)
POST
/checks
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_atstring, (date-time)(datetime)

An ISO 8601 formatted date-time string.

Example:"2020-01-01T00:00:00Z"
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"
}