Create a new identity verification.
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"). reference_id may be sent alongside profile_id. Empty address: {} or addresses: [] count as supplied address parameters and cannot be paired with profile_id.
For personal_identity_records results, controls whether SSN values in results.people[].ssn are returned in full or masked as XXX-XX-{last4}.
Used by identity verification endpoints only. Driver check endpoints use unmask_ssn instead — see that parameter for precedence rules that apply to results.requested_profile.ssn.
When the product configuration has an explicit unmask_ssn setting (available for personal_identity_records only), that setting takes precedence over this query parameter.
When no product configuration setting exists, false or omitted returns masked SSN values and true returns full SSN values.
If an SSN value is null or empty, it remains null regardless of this parameter.
The request body for creating a new identity verification.
Use either inline PII/address fields or profile_id—not both. See the POST /identity_verifications operation for details.
the request to create a new identity verification from set of PII
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.
The type of identity verification to be done.
| Enum Value | Description |
|---|---|
| pii_validation | When requesting pii_validation, the result will be returned immediately. |
| document_verification | When requesting document_verification, the result will be returned asynchronously through a pre-defined webhook. |
| personal_identity_records | When requesting personal_identity_records, enriched identity information will be returned immediately. |
| reverse_phone | When requesting reverse_phone, identity information associated with the provided phone number will be returned immediately. |
The first name of the person. Required (with last_name) when not sending full_name.
The last name of the person. Required (with first_name) when not sending full_name.
Either send the full name, or first 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. 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.
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.
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.
A US Social Security Number in XXX-XX-XXXX format. Hyphens are optional.
Primary address for the verification request. Prefer addresses for new integrations; when both are provided, address is treated as the primary entry.
On inline create (without profile_id), optional address or addresses[] are saved to the new profile.
Addresses associated with the request. Index 0 is the primary address.
On inline create, addresses are saved to the new profile.
A reference identifier for linking related records. Limited to 64 alphanumeric characters, underscores, and hyphens.
For document verification, whether the end user should receive an SMS with the collection link to the provided phone number. Defaults to false if not provided.
- Checkr Trust APIhttps://api.checkrtrust.com/v1/identity_verifications
curl -i -X POST \
'https://api.checkrtrust.com/v1/identity_verifications?include%5B%5D=profile&unmask_ssn=false' \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Content-Type: application/json' \
-d '{
"first_name": "JOHN",
"last_name": "SMITH",
"idv_type": "pii_validation",
"email": "j.doe@example.com"
}'Created. When the product has usage limits configured, the response includes X-RateLimit-Limit, X-RateLimit-Remaining, and optionally X-RateLimit-Expires.
the UUID of the identity verification.
An ISO 8601 formatted date-time string.
The structure of results depends on the value of idv_type.
the UUID of the profile.
The type of identity verification to be done.
| Enum Value | Description |
|---|---|
| pii_validation | When requesting pii_validation, the result will be returned immediately. |
| document_verification | When requesting document_verification, the result will be returned asynchronously through a pre-defined webhook. |
| personal_identity_records | When requesting personal_identity_records, enriched identity information will be returned immediately. |
| reverse_phone | When requesting reverse_phone, identity information associated with the provided phone number will be returned immediately. |
{ "id": "2b8313e8-4efd-45a1-b578-952b8313e890", "created_at": "2020-01-01T00:00:00Z", "results": { "attribute_match_scores": { … }, "overall_match_score": 50, "result_context": [ … ] }, "profile_id": "2b8313e8-4efd-45a1-b578-952b8313e890", "profile": { "id": "2b8313e8-4efd-45a1-b578-952b8313e890", "full_name": "string", "first_name": "string", "middle_name": "string", "no_middle_name": false, "last_name": "string", "dob": "19950401", "phone": "+14155552671", "country_code": "string", "email": "john.doe@example.com", "ssn": "123-45-6789", "address": { … }, "addresses": [ … ], "custom_id": "my-custom-id-123", "driver_license_state": "CA", "driver_license_number": "D1234567" }, "idv_type": "pii_validation", "reference_id": "ref-123" }