Sign in

v51

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

Retrieve Identity Verification

Retrieve a previously created Identity Verification.

post/identity_verification/get

Request body

identity_verification_idstring required

ID of the associated Identity Verification attempt.

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.

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.

Example request

{
  "identity_verification_id": "idv_52xR9LKo77r1Np"
}

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"
  }
}