Sample - Plaid API
POST/identity_verification/retry

Retry an Identity Verification

Retries an Identity Verification attempt for a customer. Provide client_user_id, template_id, and a strategy to determine how the new attempt starts; use steps only when the strategy is custom. The response identifies the new attempt and links it to the previous attempt.

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

8 body fields

Input for retrying an 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`.
template_idstringrequired
ID of the associated Identity Verification template. Like all Plaid identifiers, this is case-sensitive.
strategystringrequired
An instruction specifying what steps the new Identity Verification attempt should require the user to complete: `reset` - Restart the user at the beginning of the session, regardless of whether they successfully completed part of their previous session. `incomplete` - Start the new session at the step that the user failed in the previous session, skipping steps that have already been successfully completed. `infer` - If the most recent Identity Verification attempt associated with the given `client_user_id` has a status of `failed` or `expired`, retry using the `incomplete` strategy. Otherwise, use the `reset` strategy. `custom` - Start the new session with a custom configuration, specified by the value of the `steps` field Note: The `incomplete` strategy cannot be applied if the session's failing step is `watchlist_screening` or `risk_check`. The `infer` strategy cannot be applied if the session's status is still `active`
Allowed:resetincompleteinfercustom
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.
stepsobjectoptional
Instructions for the `custom` retry strategy specifying which steps should be required or skipped. Note: This field must be provided when the retry strategy is `custom` and must be omitted otherwise. Custom retries override settings in your Plaid Template. For example, if your Plaid Template has `verify_sms` disabled, a custom retry with `verify_sms` enabled will still require the step. The `selfie_check` step is currently not supported on the sandbox server. Sandbox requests will silently disable the `selfie_check` step when provided.
is_shareablebooleanoptional
A flag specifying whether you would like Plaid to expose a shareable URL for the verification being retried. If a value for this flag is not specified, the `is_shareable` setting from the original verification attempt will be used.
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.

1 status code
200Returns the new identity verification attempt, including its identifier, status, configured template, verification steps, collected user data, and any shareable URL.
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

client_user_id, template_id, and strategy are required. strategy must be one of reset, incomplete, infer, or custom; when strategy is custom, steps must include verify_sms, kyc_check, documentary_verification, and selfie_check. When supplied, email_address must use a valid RFC-compliant email format, phone_number must use E.164 format, and date_of_birth must use YYYY-MM-DD format.