plaid

Create a new Identity Verification

Create a new Identity Verification for the user specified by the client_user_id field. The requirements and behavior of the verification are determined by the template_id provided. If you don't know whether the associated user already has an active Identity Verification, 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 template_id. If an Identity Verification is found, it will be returned unmodified with an 200 OK HTTP status code.

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.

post/identity_verification/create

Request body

client_user_idstring

A unique ID that identifies the end user in your system. 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.

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.

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 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 template_id.

Example request

{
  "client_user_id": "your-db-id-3b24110",
  "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"
  },
  "is_idempotent": true
}

Response

idstring required

ID of the associated Identity Verification attempt.

client_user_idstring required

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

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 or 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 or 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

ID of the associated Beacon User.

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": "1990-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"
          }
        },
        "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"
        }
      }
    ]
  },
  "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",
      "linked_services": [
        "facebook"
      ]
    },
    "phone": {
      "linked_services": [
        "facebook"
      ]
    },
    "devices": [
      {
        "ip_spam_list_count": 1,
        "ip_timezone_offset": "+06:00:00"
      }
    ]
  },
  "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",
  "beacon_user_id": "becusr_42cF1MNo42r9Xj",
  "redacted_at": "2020-07-24T03:26:02Z"
}

Create a new Identity Verification

Request body

Example request

Response

Example response

Changes