Sample - Plaid API
POST/identity_verification/create

Create an Identity Verification

Creates a new Identity Verification for a user identified by client_user_id and/or user_id. Supply template_id and consent settings, and optionally prefill user information or enable idempotent creation. If user_id is provided, do not include user information in the same request; use /user/update to change that data instead.

  • RetriesRetries up to 2×, 500ms backoff, 30s timeout.

9 body fields

Identity Verification creation request containing the user identifier, template, consent settings, and optional prefilled identity data.

client_user_idstringoptional
A unique ID that identifies the end user in your system. Either a `user_id` or the `client_user_id` must be provided. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the `/link/token/create` `client_user_id` to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the `client_user_id`.
user_idstringoptional
Unique user identifier, created by calling `/user/create`. Either a `user_id` or the `client_user_id` must be provided. The `user_id` may only be used instead of the `client_user_id` if you were not a pre-existing user of `/user/create` as of December 10, 2025, or if you have since [migrated to the new User APIs](https://plaid.com/docs/api/users/migrate-to-new-user-apis); for more details, see [New User APIs](https://plaid.com/docs/api/users/user-apis). If both this field and a `client_user_id` are present in a request, the `user_id` must have been created from the provided `client_user_id`.
is_shareablebooleanrequired
A flag specifying whether you would like Plaid to expose a shareable URL for the verification being created.
template_idstringrequired
ID of the associated Identity Verification template. Like all Plaid identifiers, this is case-sensitive.
gave_consentbooleanrequired
A flag specifying whether the end user has already agreed to a privacy policy specifying that their data will be shared with Plaid for verification purposes. If `gave_consent` is set to `true`, the `accept_tos` step will be marked as `skipped` and the end user's session will start at the next step requirement.
Default:false
userobjectoptional
User information collected outside of Link, most likely via your own onboarding process. Each of the following identity fields are optional: `email_address` `phone_number` `date_of_birth` `name` `address` `id_number` Specifically, these fields are optional in that they can either be fully provided (satisfying every required field in their subschema) or omitted from the request entirely by not providing the key or value. Providing these fields via the API will result in Link skipping the data collection process for the associated user. All verification steps enabled in the associated Identity Verification Template will still be run. Verification steps will either be run immediately, or once the user completes the `accept_tos` step, depending on the value provided to the `gave_consent` field. If you are not using the shareable URL feature, you can optionally provide these fields via `/link/token/create` instead; both `/identity_verification/create` and `/link/token/create` are valid ways to provide this information. Note that if you provide a non-`null` user data object via `/identity_verification/create`, any user data fields entered via `/link/token/create` for the same `client_user_id` will be ignored when prefilling Link. The `ip_address` field is optional. Provide the end user's IP address to enable IP-based risk checks for backend-only integrations that do not use the Link SDK; when the Link SDK is used, the IP address is collected automatically. Unlike the identity fields above, `ip_address` cannot be provided via `/link/token/create`.
client_idstringoptional
Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body.
secretstringoptional
Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body.
is_idempotentbooleanoptional
An optional flag specifying how you would like Plaid to handle attempts to create an Identity Verification when an Identity Verification already exists for the provided `client_user_id` and/or `user_id`, and `template_id`. If idempotency is enabled, Plaid will return the existing Identity Verification. If idempotency is disabled, Plaid will reject the request with a `400 Bad Request` status code if an Identity Verification already exists for the supplied `client_user_id` and/or `user_id`, and `template_id`.

1 status code
200Returns the created or idempotently reused Identity Verification, including its identifiers, status, template, user data, verification steps, and any available results.
idstringrequired
ID of the associated Identity Verification attempt.
client_user_idstringrequired
A unique ID that identifies the end user in your system. Either a `user_id` or the `client_user_id` must be provided. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the `/link/token/create` `client_user_id` to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the `client_user_id`.
created_atstringrequired
An ISO8601 formatted timestamp.
completed_atstringrequired
An ISO8601 formatted timestamp.
previous_attempt_idstringrequired
The ID for the Identity Verification preceding this session. This field will only be filled if the current Identity Verification is a retry of a previous attempt.
shareable_urlstringrequired
A shareable URL that can be sent directly to the user to complete verification
templateobjectrequired
The resource ID and version number of the template configuring the behavior of a given Identity Verification.
userobjectrequired
The identity data that was either collected from the user or provided via API in order to perform an Identity Verification.
statusstringrequired
The status of this Identity Verification attempt. `active` - The Identity Verification attempt is incomplete. The user may have completed part of the session, but has neither failed nor passed. `success` - The Identity Verification attempt has completed, passing all steps defined to the associated Identity Verification template. `failed` - The user failed one or more steps in the session and was told to contact support. `expired` - The Identity Verification attempt was active for a long period of time without being completed and was automatically marked as expired. Note that sessions currently do not expire. Automatic expiration is expected to be enabled in the future. `canceled` - The Identity Verification attempt was canceled, either via the dashboard by a user, or via API. The user may have completed part of the session, but has neither failed nor passed. `pending_review` - The Identity Verification attempt template was configured to perform a screening that had one or more hits needing review.
Allowed:activesuccessfailedexpiredcanceledpending_review
stepsobjectrequired
Each step will be one of the following values: `active` - This step is the user's current step. They are either in the process of completing this step, or they recently closed their Identity Verification attempt while in the middle of this step. Only one step will be marked as `active` at any given point. `success` - The Identity Verification attempt has completed this step. `failed` - The user failed this step. This can either cause the user to fail the session as a whole, or cause them to fall back to another step depending on how the Identity Verification template is configured. A failed step does not imply a failed session. `waiting_for_prerequisite` - The user needs to complete another step first, before they progress to this step. This step may never run, depending on if the user fails an earlier step or if the step is only run as a fallback. `not_applicable` - This step will not be run for this session. `skipped` - The retry instructions that created this Identity Verification attempt specified that this step should be skipped. `expired` - This step had not yet been completed when the Identity Verification attempt as a whole expired. `canceled` - The Identity Verification attempt was canceled before the user completed this step. `pending_review` - The Identity Verification attempt template was configured to perform a screening that had one or more hits needing review. `manually_approved` - The step was manually overridden to pass by a team member in the dashboard. `manually_rejected` - The step was manually overridden to fail by a team member in the dashboard.
documentary_verificationobjectrequired
Data, images, analysis, and results from the `documentary_verification` step. This field will be `null` unless `steps.documentary_verification` has reached a terminal state of either `success` or `failed`.
selfie_checkobjectrequired
Additional information for the `selfie_check` step. This field will be `null` unless `steps.selfie_check` has reached a terminal state of either `success` or `failed`.
kyc_checkobjectrequired
Additional information for the `kyc_check` (Data Source Verification) step. This field will be `null` unless `steps.kyc_check` has reached a terminal state of either `success` or `failed`.
risk_checkobjectrequired
Additional information for the `risk_check` step.
verify_smsobjectrequired
Additional information for the `verify_sms` step.
watchlist_screening_idstringrequired
ID of the associated screening.
beacon_user_idstringdeprecatedrequired
Beacon is deprecated in favor of Plaid Protect. This field is only populated for users of the deprecated Beacon product.
user_idstringrequired
Unique user identifier, created by calling `/user/create`. Either a `user_id` or the `client_user_id` must be provided. The `user_id` may only be used instead of the `client_user_id` if you were not a pre-existing user of `/user/create` as of December 10, 2025, or if you have since [migrated to the new User APIs](https://plaid.com/docs/api/users/migrate-to-new-user-apis); for more details, see [New User APIs](https://plaid.com/docs/api/users/user-apis). If both this field and a `client_user_id` are present in a request, the `user_id` must have been created from the provided `client_user_id`.
redacted_atstringrequired
An ISO8601 formatted timestamp.
latest_scored_protect_eventobjectoptional
Information about a Protect event including Trust Index score and fraud attributes.
request_idstringrequired
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

Error handling

template_id, is_shareable, and gave_consent are required, and at least one of client_user_id or user_id must be provided. If you provide user_id, omit user; if you provide user, nested name requires given_name and family_name, address requires country, and email_address, phone_number, and date_of_birth must use their specified formats.