# Create driver check

Create a new driver check.
For `motor_vehicle_report` checks in Washington (`WA`), only DPPA purposes `employment` and `insurance` are supported.
If your account is configured with a different DPPA purpose, requests for `motor_vehicle_report` checks in `WA` will be rejected.
This restriction does not apply to `driver_license_status` checks.

Endpoint: POST /driver_checks
Version: 1.0
Security: get-bearer-token-using-oauth2

## Security:

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

## Query parameters:

  - `unmask_ssn` (boolean)
    Controls whether SSN values in `results.requested_profile.ssn` (and
`results_v2.requested_profile.ssn` for driver license status checks) are
returned in full or masked as `XXX-XX-{last4}`.

Used by driver check endpoints. For identity verification endpoints, see
`unmask_ssn_identity_verification` instead — precedence rules differ.

When omitted, the account's product configuration `unmask_ssn` setting
determines whether SSNs are unmasked. When explicitly set to `true` or
`false`, the query parameter overrides the product configuration.

Defaults to masked when the product configuration has no `unmask_ssn`
setting.

## Request body:

  - `application/json` (unknown)
    The request to create a driver check.
Use either inline PII/address fields or `profile_id`—not both. See the POST `/driver_checks` operation for details.

## Request fields (application/json):

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

  - `check_type` (string, required)
    Enum: "driver_license_status", "motor_vehicle_report"

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

## Response 201:

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

## Response 201 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

  - `completed_at` (any)
    A datetime, or null if not completed.

  - `results` (any)
    Results, or null if not completed.

  - `results.requested_profile` (object)
    The inputs used to create the driver check. Fields that weren't provided will not be included.

  - `results.requested_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).

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

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

  - `results.requested_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.

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

  - `results.requested_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

  - `results.requested_profile.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.requested_profile.country_code` (string)
    The phone country calling code supplied for a reverse phone verification (for example, "1" or "54").

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

  - `results.requested_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

  - `results.requested_profile.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.requested_profile.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.requested_profile.address.city` (string, required)
    The name of the city or municipality.
    Example: Frankfort

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

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

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

  - `results.requested_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.

  - `results.requested_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

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

  - `results.passenger` (object)

  - `results.passenger.validity` (string)
    Enum: "VALID", "INVALID", "NOT FOUND"

  - `check_type` (string)
    Enum: "driver_license_status"

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

  - `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.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.driver_license_number` (string)
    The driver license number. Format dependent on State.
    Example: D1234567

## Response 400:

  - `400` (unknown)
    Error response

## Response 400 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 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 403:

  - `403` (unknown)
    Error response

## Response 403 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 409:

  - `409` (unknown)
    Conflict — the upstream driver-check provider rejected the order (for example, a
conflicting or duplicate request). Inspect the error payload for provider details.
The check is not created; correct the request or retry after resolving the conflict.

## Response 409 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 429:

  - `429` (unknown)
    Too Many Requests - the product configuration has reached its usage limit or product access has expired.
When usage limits are configured, the response includes X-RateLimit-* headers (see below).

## Response 429 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 429 headers (application/json):

  - `X-RateLimit-Limit` (string)
    Maximum number of API calls allowed for this product configuration.
    Example: 100

  - `X-RateLimit-Remaining` (string)
    Number of calls remaining in the current limit period.
    Example: 0

  - `X-RateLimit-Expires` (string | null)
    ISO 8601 timestamp after which product access expires (present only when access_expires_at is set).

## 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

## Callback:

  - `onSearchCompleted` (unknown)
    Driver Check Completion Webhook Callback (webhook) triggered when the driver check search is finished.
Driver check clients must configure this webhook URL, either in the dashboard under Configuration or with their Checkr Account Executive.
The payload contains the results for either `driver_license_status` or `motor_vehicle_report` checks, depending on what was initiated. See the schemas below for details.
Refer to the main [Webhooks](./index.md#webhooks) documentation for details on signature verification.

## Callback request body:

  - `application/json` (unknown)
    Payload containing the driver check results

## Callback request fields (application/json):

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

  - `object` (string, required)
    Enum: "event"

  - `type` (string, required)
    Enum: "driver_license_status.completed"

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

  - `data` (object, required)

  - `data.results` (object)

  - `data.results.requested_profile` (object)
    The inputs used to create the driver check. Fields that weren't provided will not be included.

  - `data.results.requested_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).

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

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

  - `data.results.requested_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.

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

  - `data.results.requested_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

  - `data.results.requested_profile.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

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

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

  - `data.results.requested_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

  - `data.results.requested_profile.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.

  - `data.results.requested_profile.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

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

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

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

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

  - `data.results.requested_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.

  - `data.results.requested_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

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

  - `data.results.passenger` (object)

  - `data.results.passenger.validity` (string)
    Enum: "VALID", "INVALID", "NOT FOUND"

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

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

  - `data.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).

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

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

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

  - `data.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

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

  - `data.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

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

  - `data.check_type` (string)
    Enum: "driver_license_status"

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

## Callback response 2xx:

  - `2xx` (unknown)
    Return any 2xx status (e.g. 200 OK, 201 Created, 204 No Content) when you successfully process the callback.
We treat any 2xx as success and will not retry the POST.

## Callback response 4xx:

  - `4xx` (unknown)
    HTTP status codes in the 4xx range indicate client errors (e.g., 400 Bad Request, 401 Unauthorized).
Returning a 4xx status may result in retries depending on the specific status code.