Sign in

v51

latestOpenAPI 3.0.0raw.githubusercontent.com2026-07-313352,3122.9 MB
plaid

Retry an Identity Verification

Allow a customer to retry their Identity Verification

post/identity_verification/retry

Request body

client_user_idstring required

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_idstring required

ID of the associated Identity Verification template. Like all Plaid identifiers, this is case-sensitive.

strategy'reset' | 'incomplete' | 'infer' | 'custom' required

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

is_shareableboolean nullable

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_idstring

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.

secretstring

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.

Example request

{
  "client_user_id": "your-db-id-3b24110",
  "template_id": "idvtmp_4FrXJvfQU3zGUR",
  "user": {
    "email_address": "user@example.com",
    "phone_number": "+12345678909",
    "date_of_birth": "1990-05-29",
    "name": {
      "given_name": "Leslie",
      "family_name": "Knope"
    },
    "address": {
      "street": "123 Main St.",
      "street2": "Unit 42",
      "city": "Pawnee",
      "region": "IN",
      "postal_code": "46001",
      "country": "US"
    },
    "id_number": {
      "value": "123456789",
      "type": "us_ssn"
    }
  },
  "is_shareable": true
}

Response

OK

idstring required

ID of the associated Identity Verification attempt.

client_user_idstring required

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_atstring date-time required

An ISO8601 formatted timestamp.

completed_atstring date-time nullable required

An ISO8601 formatted timestamp.

previous_attempt_idstring nullable required

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_urlstring nullable required

A shareable URL that can be sent directly to the user to complete verification

status'active' | 'success' | 'failed' | 'expired' | 'canceled' | 'pending_review' required

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.

watchlist_screening_idstring nullable required

ID of the associated screening.

beacon_user_idstring nullable required

Beacon is deprecated in favor of Plaid Protect. This field is only populated for users of the deprecated Beacon product.

user_idstring nullable required

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; for more details, see New 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_atstring date-time nullable required

An ISO8601 formatted timestamp.

request_idstring required

A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

Example response

{
  "id": "idv_52xR9LKo77r1Np",
  "client_user_id": "your-db-id-3b24110",
  "created_at": "2020-07-24T03:26:02Z",
  "completed_at": "2020-07-24T03:26:02Z",
  "previous_attempt_id": "idv_42cF1MNo42r9Xj",
  "shareable_url": "https://flow.plaid.com/verify/idv_4FrXJvfQU3zGUR?key=e004115db797f7cc3083bff3167cba30644ef630fb46f5b086cde6cc3b86a36f",
  "template": {
    "id": "idvtmp_4FrXJvfQU3zGUR",
    "version": 2
  },
  "user": {
    "phone_number": "+12345678909",
    "date_of_birth": "1990-05-29",
    "ip_address": "192.0.2.42",
    "email_address": "user@example.com",
    "name": {
      "given_name": "Leslie",
      "family_name": "Knope"
    },
    "address": {
      "street": "123 Main St.",
      "street2": "Unit 42",
      "city": "Pawnee",
      "region": "IN",
      "postal_code": "46001",
      "country": "US"
    },
    "id_number": {
      "value": "123456789",
      "type": "us_ssn"
    }
  },
  "status": "success",
  "steps": {
    "accept_tos": "success",
    "verify_sms": "success",
    "kyc_check": "success",
    "documentary_verification": "success",
    "selfie_check": "success",
    "watchlist_screening": "success",
    "risk_check": "success"
  },
  "documentary_verification": {
    "status": "success",
    "documents": [
      {
        "status": "success",
        "attempt": 1,
        "images": {
          "original_front": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/original_front.jpeg",
          "original_back": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/original_back.jpeg",
          "cropped_front": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/cropped_front.jpeg",
          "cropped_back": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/cropped_back.jpeg",
          "face": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/face.jpeg"
        },
        "extracted_data": {
          "id_number": "AB123456",
          "category": "drivers_license",
          "expiration_date": "2030-05-29",
          "issue_date": "2020-05-29",
          "issuing_country": "US",
          "issuing_region": "IN",
          "date_of_birth": "1990-05-29",
          "address": {
            "street": "123 Main St. Unit 42",
            "city": "Pawnee",
            "region": "IN",
            "postal_code": "46001",
            "country": "US"
          },
          "name": {
            "given_name": "Leslie",
            "family_name": "Knope"
          }
        },
        "analysis": {
          "authenticity": "match",
          "image_quality": "high",
          "extracted_data": {
            "name": "match",
            "date_of_birth": "match",
            "expiration_date": "not_expired"
          },
          "aamva_verification": {
            "is_verified": true
          }
        },
        "redacted_at": "2020-07-24T03:26:02Z"
      }
    ]
  },
  "selfie_check": {
    "status": "success",
    "selfies": [
      {
        "status": "success",
        "attempt": 1,
        "capture": {
          "image_url": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/selfie/liveness.jpeg",
          "video_url": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/selfie/liveness.webm"
        },
        "analysis": {
          "age_check": {
            "status": "match",
            "reported_age": 36,
            "age_estimate_lower_bound": 32,
            "age_estimate_upper_bound": 38
          }
        }
      }
    ]
  },
  "kyc_check": {
    "status": "success",
    "address": {
      "summary": "match",
      "po_box": "yes",
      "type": "residential",
      "street": "match",
      "city": "match",
      "region": "match",
      "postal_code": "match",
      "international_details": {
        "building": "match",
        "county": "match",
        "district": "match",
        "house_number": "match",
        "subpremise": "match",
        "thoroughfare": "match"
      }
    },
    "name": {
      "summary": "match",
      "given_name": "match",
      "family_name": "match"
    },
    "date_of_birth": {
      "summary": "match",
      "day": "match",
      "month": "match",
      "year": "match"
    },
    "id_number": {
      "summary": "match"
    },
    "phone_number": {
      "summary": "match",
      "area_code": "match"
    }
  },
  "risk_check": {
    "status": "success",
    "behavior": {
      "user_interactions": "risky"
    },
    "email": {
      "is_deliverable": "yes",
      "breach_count": 1,
      "first_breached_at": "1990-05-29",
      "last_breached_at": "1990-05-29",
      "domain_registered_at": "1990-05-29",
      "domain_is_free_provider": "yes",
      "domain_is_custom": "yes",
      "domain_is_disposable": "yes",
      "top_level_domain_is_suspicious": "yes",
      "is_edu": "no_data",
      "includes_date_of_birth": "no_data",
      "name": "match",
      "linked_services": [
        "facebook"
      ]
    },
    "phone": {
      "linked_services": [
        "facebook"
      ]
    },
    "devices": [
      {
        "ip_spam_list_count": 1,
        "ip_timezone_offset": "+06:00:00"
      }
    ],
    "facial_duplicates": [
      {
        "id": "idv_52xR9LKo77r1Np",
        "similarity": 95,
        "matched_after_completed": true
      }
    ],
    "trust_index_score": 86
  },
  "verify_sms": {
    "status": "success",
    "verifications": [
      {
        "status": "success",
        "attempt": 1,
        "phone_number": "+12345678909",
        "delivery_attempt_count": 1,
        "solve_attempt_count": 1,
        "initially_sent_at": "2020-07-24T03:26:02Z",
        "last_sent_at": "2020-07-24T03:26:02Z",
        "redacted_at": "2020-07-24T03:26:02Z"
      }
    ]
  },
  "watchlist_screening_id": "scr_52xR9LKo77r1Np",
  "user_id": "usr_dddAs9ewdcDQQQ",
  "redacted_at": "2020-07-24T03:26:02Z",
  "latest_scored_protect_event": {
    "event_id": "ptevt_7AJYTMFxRUgJ",
    "timestamp": "2020-07-24T03:26:02Z"
  }
}