# Get identity verification

Get a single identity verification with a given id

Endpoint: GET /identity_verifications/{identity_verification_id}
Version: 1.0
Security: get-bearer-token-using-oauth2

## Security:

  - `get-bearer-token-using-oauth2` (unknown)
    oauth2

## Path parameters:

  - `identity_verification_id` (string, required)
    the uuid identifying the identity verification

## Query parameters:

  - `include[]` (array)
    Embed the profile in the response in place of `profile_id`.

  - `unmask_ssn` (boolean)
    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.

## Response 200:

  - `200` (unknown)
    OK

## Response 200 fields (application/json):

  - `id` (string)
    A universally unique identifier (UUID) in standard format.
    Example: 2b8313e8-4efd-45a1-b578-952b8313e890

  - `created_at` (string)
    An ISO 8601 formatted date-time string.
    Example: 2020-01-01T00:00:00Z

  - `results` (any)
    The structure of results depends on the value of idv_type.

  - `results.attribute_match_scores` (object)
    attribute match scores
    Example: {"first_name":100,"last_name":100,"dob":100,"phone":100,"email":0,"address":100,"city":100,"state":100,"zip_code":100,"ssn":0}

  - `results.attribute_match_scores.first_name` (integer)
    0 if an attribute does not match, 100 if it matches
    Enum: 0, 100

  - `results.overall_match_score` (integer)
    0 if no attributes match, 50 if some attributes match, 100 if all attributes match
    Enum: 0, 50, 100

  - `results.result_context` (array)

  - `results.result_context.code` (string)
    A stable code for the reason or context
    Example: CT-0195

  - `results.result_context.title` (string)
    A user-friendly description of the reason or context
    Example: Address is correlated with a past address

  - `results.result_context.category` (string)
    Category derived from the provider reason code.
    Enum: "informational", "rejection", "unknown"

  - `results.status` (string)
    The current status of the document verification process.
    Enum: "started", "documents_collected", "complete"

  - `results.result` (string)
    The final result of the verification, or null if not complete.
    Enum: "accept", "reject", "resubmit", "failed"

  - `results.errors` (array)
    An array of error objects.

  - `results.errors.code` (string, required)
    A machine-readable error code.
    Example: invalid_request

  - `results.errors.title` (string, required)
    A human-readable error title.
    Example: Invalid Request

  - `results.errors.source` (object)
    An object containing references to the source of the error.

  - `results.errors.source.pointer` (string)
    A JSON Pointer [RFC6901] to the associated entity in the request document.
    Example: /data/attributes/first_name

  - `results.collection_link` (object)

  - `results.collection_link.url` (string)
    URL for the document collection application.

  - `results.collection_link.qr_code` (string)
    Base64 encoded PNG image of a QR code linking to the collection URL.

  - `results.result_context` (array)
    Array of objects describing reasons or context associated with the result.
    Example: [{"code":"CT-0167","title":"First name extracted from document correlates with input name","category":"informational"},{"code":"CT-0171","title":"Document number extracted from document correlates wit…

  - `results.document_type` (object)

  - `results.document_type.type` (string)
    The type of document identified (e.g., Drivers License, Passport).
    Example: Drivers License

  - `results.document_type.country` (string)
    The country of issuance.
    Example: USA

  - `results.document_type.state` (string)
    The state/province of issuance (if applicable).
    Example: CO

  - `results.document_data` (object)

  - `results.document_data.first_name` (string)
    First name extracted from the document.
    Example: Dwayne

  - `results.document_data.sur_name` (string)
    Last name extracted from the document.
    Example: Denver

  - `results.document_data.full_name` (string)
    Full name extracted from the document.
    Example: Dwayne Denver

  - `results.document_data.address` (string)
    Address extracted from the document.
    Example: 123 Example Street, New York City, NY 10001

  - `results.document_data.parsed_address` (object)
    Address components parsed from the extracted address.

  - `results.document_data.parsed_address.physical_address` (string)
    The primary address line of the address.

  - `results.document_data.parsed_address.physical_address2` (string)
    The secondary address line of the address.

  - `results.document_data.parsed_address.city` (string)
    The city of the address.

  - `results.document_data.parsed_address.state` (string)
    The state of the address.

  - `results.document_data.parsed_address.country` (string)
    The country of the address.

  - `results.document_data.parsed_address.zip` (string)
    The ZIP code of the address.

  - `results.document_data.document_number` (string)
    Document identification number.
    Example: 000000000

  - `results.document_data.dob` (string)
    Date of birth extracted from the document.
    Example: 1990-01-01

  - `results.document_data.issue_date` (string)
    Date the document was issued.
    Example: 2020-01-01

  - `results.document_data.expiration_date` (string)
    Date the document expires.
    Example: 2027-01-01

  - `results.request` (object)
    The request parameters used for the search

  - `results.request.first_name` (string)
    The first name of the person

  - `results.request.middle_name` (string)
    The middle name of the person

  - `results.request.last_name` (string)
    The last name of the person

  - `results.request.dob` (string)
    A date in the form YYYYMMDD.
    Example: 19950401

  - `results.request.phone` (string)
    A phone number in the form +[country code][number including area code].
([E.164 format](https://en.wikipedia.org/wiki/E.164)).
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

  - `results.request.email` (string)
    An email address.
    Example: john.doe@example.com

  - `results.request.ssn` (string)
    A US Social Security Number in XXX-XX-XXXX format. Hyphens are optional.
    Example: 123-45-6789

  - `results.request.address` (object)
    A US postal address supplied in a **request** (for example on check create or profile create/update).
When this object is present, `street`, `city`, `state`, and `zip_code` are required.

  - `results.request.address.street` (string, required)
    Street address, including house/building number and street name.
Apartment or unit numbers may be included; they are stored but are not used for criminal-record address matching.
    Example: 123 Main St

  - `results.request.address.city` (string, required)
    The name of the city or municipality.
    Example: Frankfort

  - `results.request.address.state` (string, required)
    A two-letter US state code.
    Example: CA

  - `results.request.address.zip_code` (string, required)
    US Postal Service ZIP code (5-digit or 9-digit ZIP+4 format).
    Example: 94105

  - `results.request.address.country` (string)
    A two-letter country code in ISO 3166-1 alpha-2 format.
    Example: US

  - `results.request.reference_id` (string)
    A reference identifier for linking related records. Limited to 64 alphanumeric characters, underscores, and hyphens.
    Example: ref-123

  - `results.people` (array)
    Array of identity records found matching the search criteria

  - `results.people.name` (object)
    The person's name components

  - `results.people.name.first_name` (string)

  - `results.people.name.middle_name` (string)

  - `results.people.name.last_name` (string)

  - `results.people.name.full_name` (string)

  - `results.people.dobs` (array)
    Array of dates of birth associated with this identity (format YYYYMMDD, with 00 for unknown components)

  - `results.people.phones` (array)
    Array of phone numbers associated with this identity

  - `results.people.ssn` (any)
    Social Security Number for this identity record. Not enabled by default;
contact your Checkr Account Executive or Customer Success
representative if you need SSN in results.
When SSN unmasking is disabled, values are returned masked as
`XXX-XX-{last4}` (see the `unmask_ssn` query parameter). May be null
when the provider has no SSN on file for this record.
    Example: XXX-XX-1234

  - `results.people.addresses` (array)
    Array of addresses associated with this identity

  - `results.people.addresses.street` (string)

  - `results.people.addresses.city` (string)

  - `results.people.addresses.state` (string)

  - `results.people.addresses.zip_code` (string)

  - `results.people.addresses.county` (string)
    County name

  - `results.people.addresses.country` (string)

  - `results.people.addresses.from_date` (string)
    First date the person was associated with this address

  - `results.people.addresses.to_date` (string)
    Last date the person was associated with this address

  - `results.people.aliases` (array)
    Array of name aliases associated with this identity

  - `results.people.aliases.first_name` (string)

  - `results.people.aliases.middle_name` (string)

  - `results.people.aliases.last_name` (string)

  - `results.people.aliases.full_name` (string)

  - `results.phone_info` (object)
    Technical and geographic information about the phone number.

  - `results.phone_info.operating_company` (object)
    The operating carrier associated with the phone number.

  - `results.phone_info.operating_company.category_description` (string)
    Description of the carrier category.

  - `results.phone_info.operating_company.name` (string)
    Legal name of the operating company.

  - `results.phone_info.operating_company.dba` (string)
    Doing-business-as name of the operating company.

  - `results.phone_info.operating_company.common_name` (string)
    Common name of the operating company.

  - `results.phone_info.operating_company.type` (string)
    Type of operating company.

  - `results.phone_info.rate_center` (object)
    Geographic rate center information for the phone number.

  - `results.phone_info.rate_center.lata` (object)
    Local Access and Transport Area information.

  - `results.phone_info.rate_center.lata.code` (string)

  - `results.phone_info.rate_center.lata.state` (string)

  - `results.phone_info.rate_center.lata.state_name` (string)

  - `results.phone_info.rate_center.lata.country` (string)

  - `results.phone_info.rate_center.lata.country_name` (string)

  - `results.phone_info.rate_center.lata.location` (string)

  - `results.phone_info.rate_center.bta` (object)
    Basic Trading Area information.

  - `results.phone_info.rate_center.bta.code` (string)

  - `results.phone_info.rate_center.bta.name` (string)

  - `results.phone_info.rate_center.mtas` (array)
    Major Trading Areas associated with the rate center.

  - `results.phone_info.rate_center.mtas.code` (integer)

  - `results.phone_info.rate_center.mtas.country` (string)

  - `results.phone_info.rate_center.mtas.market_name` (string)

  - `results.phone_info.rate_center.cbsas` (array)
    Core Based Statistical Areas associated with the rate center.

  - `results.phone_info.rate_center.cbsas.code` (integer)

  - `results.phone_info.rate_center.cbsas.csa` (integer)

  - `results.phone_info.rate_center.cbsas.area_name` (string)

  - `results.phone_info.rate_center.cbsas.area_type` (string)

  - `results.phone_info.rate_center.cbsas.state` (string)

  - `results.phone_info.rate_center.counties` (array)
    Counties associated with the rate center.

  - `results.phone_info.rate_center.counties.fips_code` (string)
    US county FIPS code

  - `results.phone_info.rate_center.counties.name` (string)

  - `results.phone_info.rate_center.counties.type` (string)

  - `results.phone_info.rate_center.counties.state` (string)

  - `results.phone_info.rate_center.counties.state_name` (string)

  - `results.phone_info.rate_center.counties.county` (string)

  - `results.phone_info.rate_center.counties.country` (string)

  - `results.phone_info.rate_center.counties.country_name` (string)

  - `results.phone_info.rate_center.counties.land_area_square_miles` (number)

  - `results.phone_info.rate_center.counties.population_in_2006` (integer)

  - `results.phone_info.rate_center.zip_codes` (array)
    ZIP codes associated with the rate center.

  - `results.phone_info.rate_center.city` (string)

  - `results.phone_info.rate_center.code` (string)

  - `results.phone_info.rate_center.type` (string)

  - `results.phone_info.rate_center.country` (string)

  - `results.phone_info.rate_center.country_name` (string)

  - `results.phone_info.rate_center.state` (string)

  - `results.phone_info.rate_center.state_name` (string)

  - `results.phone_info.rate_center.time_zone` (string)

  - `results.phone_info.rate_center.time_zone_name` (string)

  - `results.phone_info.rate_center.dst_recognized` (string)
    Whether daylight saving time is recognized in this area.

  - `results.phone_info.npa` (integer)
    Numbering Plan Area (area code).

  - `results.phone_info.nxx` (integer)
    Central office code (exchange).

  - `results.phone_info.block_id` (string)
    Block identifier for the phone number.

  - `results.phone_info.line_type` (string)
    Type of phone line (e.g. Mobile, Landline, VOIP).

  - `results.phone_info.central_office_name` (string)
    Name of the central office serving this number.

  - `results.phone_info.switch` (string)
    Switch identifier for the central office.

  - `results.phone_info.derived_from_npa` (integer)
    Original NPA if the number was derived from a different area code.

  - `results.phone_info.new_npa` (string)
    New NPA if the number has been reassigned.

  - `results.phone_info.overlay` (string)
    Overlay area code, if applicable.

  - `results.phone_info.nxx_type` (string)
    Type classification of the NXX code.

  - `results.phone_info.nxx_description` (string)
    Description of the NXX type.

  - `results.persons` (array)
    Array of identity records associated with the phone number.

  - `results.persons.names` (array)
    Names associated with this identity.

  - `results.persons.names.full_name` (string)

  - `results.persons.names.first_name` (string)

  - `results.persons.names.middle_name` (string)

  - `results.persons.names.last_name` (string)

  - `results.persons.names.prefixes` (string)

  - `results.persons.names.maiden_name` (string)

  - `results.persons.names.suffixes` (string)

  - `results.persons.addresses` (array)
    Addresses associated with this identity.

  - `results.persons.addresses.address1` (string)

  - `results.persons.addresses.address2` (string)

  - `results.persons.addresses.address3` (string)

  - `results.persons.addresses.house_num` (string)

  - `results.persons.addresses.unit_num` (string)

  - `results.persons.addresses.unit_type` (string)

  - `results.persons.addresses.county` (string)

  - `results.persons.addresses.county_code` (string)

  - `results.persons.addresses.city` (string)

  - `results.persons.addresses.state` (string)

  - `results.persons.addresses.state_code` (string)

  - `results.persons.addresses.city_state` (string)

  - `results.persons.addresses.postal_code` (string)

  - `results.persons.addresses.country` (string)

  - `results.persons.addresses.country_code` (string)

  - `results.persons.addresses.zip_code` (string)

  - `results.persons.addresses.zip_code4` (string)

  - `results.persons.addresses.date_from` (string)

  - `results.persons.addresses.date_from_year` (integer)

  - `results.persons.addresses.date_from_month` (integer)

  - `results.persons.addresses.date_from_day` (integer)

  - `results.persons.addresses.date_to` (string)

  - `results.persons.addresses.date_to_year` (integer)

  - `results.persons.addresses.date_to_month` (integer)

  - `results.persons.addresses.date_to_day` (integer)

  - `results.persons.phones` (array)
    Phone numbers associated with this identity.

  - `results.persons.phones.phone` (string)

  - `results.persons.phones.country_code` (string)

  - `results.persons.phones.formatted` (string)

  - `results.persons.phones.valid_since` (string)

  - `results.persons.phones.type` (string)

  - `results.persons.email` (string)
    Email address associated with this identity.

  - `results.persons.days_email_has_been_active` (string)
    Number of days the email address has been active.

  - `results.persons.gender` (string)
    Gender associated with this identity.
    Enum: "unknown", "male", "female"

  - `results.persons.dob` (string)
    Date of birth associated with this identity.

  - `results.persons.social_profiles` (array)
    Social media profiles associated with this identity.

  - `results.persons.social_profiles.exists` (boolean)

  - `results.persons.social_profiles.user_name` (string)

  - `results.persons.social_profiles.num_friends` (string)

  - `results.persons.social_profiles.profile_url` (string)

  - `results.persons.social_profiles.image_url` (string)

  - `results.persons.social_profiles.site` (string)

  - `results.persons.social_profiles.site_url` (string)

  - `results.persons.user_ids` (array)
    User identifiers associated with this identity.

  - `results.persons.user_names` (array)
    Usernames associated with this identity.

  - `results.persons.relationships` (array)
    Relationships associated with this identity.

  - `results.date_executed` (string)
    The date and time the phone search was executed.

  - `results.total_time_in_seconds` (number)
    Total time taken to execute the phone search, in seconds.

  - `idv_type` (string)
    The type of identity verification to be done.
    Enum: "pii_validation", "document_verification", "personal_identity_records", "reverse_phone"

  - `profile_id` (string, required)
    Identifier of an existing profile containing search criteria.
    Example: 2b8313e8-4efd-45a1-b578-952b8313e890

  - `profile` (object, required)
    A profile containing personal information used for checks and verifications.

  - `profile.full_name` (string)
    The full name of the person. Must not be combined with first_name, middle_name, or last_name.
May be combined with `no_middle_name` on create/update; when that flag is `true`, parsing
stores only a first name and surname (any middle token is folded into the last name).

  - `profile.first_name` (string)
    The first name of the person.

  - `profile.middle_name` (string)
    The middle name of the person. Can be null if not provided.

  - `profile.no_middle_name` (boolean)
    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.

  - `profile.last_name` (string)
    The last name of the person.

  - `profile.dob` (string)
    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

  - `profile.country_code` (string)
    The phone country calling code supplied for a reverse phone verification (for example, "1" or "54").

  - `profile.ssn` (any)
    US Social Security Number.
**Masked by default** — API responses return `XXX-XX-{last4}`. Full SSN is
available via `?unmask_ssn=true` on endpoints that support it (driver checks and
identity verifications), subject to your account's product configuration. Contact
your account representative to enable SSN unmasking.
**Always `null` on list/index endpoints** (e.g. `GET /profiles`, `GET /checks`), regardless
of masking or unmasking settings. Fetch the individual resource (e.g. `GET /profiles/{id}`)
to see the masked or unmasked value for a specific record.
May also be null on a single-resource response when no SSN was provided.
    Example: XXX-XX-6789

  - `profile.addresses` (array)
    **Request only.** Array of addresses supplied by the caller. Index 0 is the primary address.
When the property is provided, at least one address entry is required.
Maximum 30 addresses.
For check requests, records may be matched against any address in the array.
The singular `address` field remains supported for backwards compatibility and maps to the primary address.

  - `profile.custom_id` (string)
    An identifier of your choice, if you wish to use one. Limited to 64 alphanumeric characters, underscores, and hyphens.
    Example: my-custom-id-123

  - `profile.driver_license_number` (string)
    The driver license number. Format dependent on State.
    Example: D1234567

## Response 401:

  - `401` (unknown)
    Error response

## Response 401 fields (application/json):

  - `code` (string, required)
    A machine-readable error code.
    Example: invalid_request

  - `title` (string, required)
    A human-readable error title.
    Example: Invalid Request

  - `source` (object)
    An object containing references to the source of the error.

  - `source.pointer` (string)
    A JSON Pointer [RFC6901] to the associated entity in the request document.
    Example: /data/attributes/first_name

## Response 404:

  - `404` (unknown)
    Error response

## Response 404 fields (application/json):

  - `code` (string, required)
    A machine-readable error code.
    Example: invalid_request

  - `title` (string, required)
    A human-readable error title.
    Example: Invalid Request

  - `source` (object)
    An object containing references to the source of the error.

  - `source.pointer` (string)
    A JSON Pointer [RFC6901] to the associated entity in the request document.
    Example: /data/attributes/first_name

## Response 500:

  - `500` (unknown)
    Error response

## Response 500 fields (application/json):

  - `code` (string, required)
    A machine-readable error code.
    Example: invalid_request

  - `title` (string, required)
    A human-readable error title.
    Example: Invalid Request

  - `source` (object)
    An object containing references to the source of the error.

  - `source.pointer` (string)
    A JSON Pointer [RFC6901] to the associated entity in the request document.
    Example: /data/attributes/first_name