Sample - Plaid API
POST/identity_verification/get

Retrieve an Identity Verification

Retrieves a previously created Identity Verification attempt. Use identity_verification_id to identify the verification whose status, configured template, collected user data, and step results you want to inspect. The response includes timestamps and any available documentary, selfie, KYC, risk, and SMS verification details.

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

3 body fields

Request identifying the Identity Verification attempt to retrieve.

identity_verification_idstringrequired
ID of the associated Identity Verification attempt.
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.
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.

1 status code
200Returns the Identity Verification attempt, including its identifiers, timestamps, status, template, user data, verification steps, and available verification 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

identity_verification_id is required and must identify the Identity Verification attempt you want to retrieve. client_id and secret may be supplied in the request body or their corresponding headers.