Sign in

v51

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

Create a new Identity Verification

Create a new Identity Verification for the user specified by the client_user_id and/or user_id field. At least one of these two fields must be provided. The requirements and behavior of the verification are determined by the template_id provided. If user_id is provided, there must be an associated user; otherwise, an error will be returned.

If you don't know whether an active Identity Verification exists for a given client_user_id and/or user_id, you can specify "is_idempotent": true in the request body. With idempotency enabled, a new Identity Verification will only be created if one does not already exist for the associated client_user_id and/or user_id, and template_id. If an Identity Verification is found, it will be returned unmodified with a 200 OK HTTP status code.

If user_id is not provided, you can also use this endpoint to supply information you already have collected about the user; if any of these fields are specified, the screens prompting the user to enter them will be skipped during the Link flow. If user_id is provided, user information can not be included in the request body. Please use the /user/update endpoint to update user data instead.

post/identity_verification/create

Request body

client_user_idstring

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_idstring

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.

is_shareableboolean required

A flag specifying whether you would like Plaid to expose a shareable URL for the verification being created.

template_idstring required

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

gave_consentboolean required

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.

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.

is_idempotentboolean nullable

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.

Example request

{
  "client_user_id": "your-db-id-3b24110",
  "user_id": "usr_dddAs9ewdcDQQQ",
  "is_shareable": true,
  "template_id": "idvtmp_4FrXJvfQU3zGUR",
  "gave_consent": true,
  "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"
    },
    "client_user_id": "your-db-id-3b24110",
    "ip_address": "192.0.2.42"
  },
  "is_idempotent": 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"
  }
}