Identity Verification

API reference for Identity Verification endpoints and webhooks

Endpoints
/identity_verification/createCreate a new identity verification
/identity_verification/getRetrieve a previously created identity verification
/identity_verification/listFilter and list identity verifications
/identity_verification/retryAllow a user to retry an identity verification
Webhooks
STATUS_UPDATEDThe status of an identity verification has been updated
STEP_UPDATEDA step in the identity verification process has been completed
RETRIEDAn identity verification has been retried

Endpoints

/identity_verification/create

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.

identity_verification/create

Request fields and example

is_shareable
requiredboolean
A flag specifying whether you would like Plaid to expose a shareable URL for the verification being created.
template_id
requiredstring
ID of the associated Identity Verification template.
gave_consent
requiredboolean
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.

Default: false
user
requiredobject
User information collected outside of Link, most likely via your own onboarding process.
Each of the following identity fields are optional:
email_address
phone_number
date_of_birth
name
address
id_number
Specifically, these fields are optional in that they can either be fully provided (satisfying every required field in their subschema) or omitted from the request entirely by not providing the key or value. Providing these fields via the API will result in Link skipping the data collection process for the associated user. All verification steps enabled in the associated Identity Verification Template will still be run. Verification steps will either be run immediately, or once the user completes the accept_tos step, depending on the value provided to the gave_consent field.
client_user_id
requiredstring
An identifier to help you connect this object to your internal systems. For example, your database ID corresponding to this object.

Min length: 1
email_address
string
A valid email address.

Format: email
phone_number
string
A phone number in E.164 format.
date_of_birth
string
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

Format: date
name
object
The full name provided by the user. If the user has not submitted their name, this field will be null. Otherwise, both fields are guaranteed to be filled.
given_name
requiredstring
A string with at least one non-whitespace character, with a max length of 100 characters.
family_name
requiredstring
A string with at least one non-whitespace character, with a max length of 100 characters.
address
object
Home address for the user.
street
requiredstring
The primary street portion of an address. If the user has submitted their address, this field will always be filled.
street2
string
Extra street information, like an apartment or suite number.
city
requiredstring
City from the end user's address
region
requiredstring
An ISO 3166-2 subdivision code. Related terms would be "state", "province", "prefecture", "zone", "subdivision", etc.
postal_code
requiredstring
The postal code for the associated address. Between 2 and 10 alphanumeric characters. For US-based addresses this must be 5 numeric digits.
country
requiredstring
Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

Min length: 2
id_number
object
ID number submitted by the user, currently used only for the Identity Verification product. If the user has not submitted this data yet, this field will be null. Otherwise, both fields are guaranteed to be filled.
value
requiredstring
Value of identity document value typed in by user. Alpha-numeric, with all formatting characters stripped.
type
requiredstring
A globally unique and human readable ID type, specific to the country and document category. For more context on this field, see Hybrid Input Validation.

Possible values: ar_dni, au_drivers_license, au_passport, br_cpf, ca_sin, cl_run, cn_resident_card, co_nit, dk_cpr, eg_national_id, es_dni, es_nie, hk_hkid, in_pan, it_cf, jo_civil_id, jp_my_number, ke_huduma_namba, kw_civil_id, mx_curp, mx_rfc, my_nric, ng_nin, nz_drivers_license, om_civil_id, ph_psn, pl_pesel, ro_cnp, sa_national_id, se_pin, sg_nric, tr_tc_kimlik, us_ssn, us_ssn_last_4, za_smart_id
client_id
string
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.
secret
string
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_idempotent
boolean
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.
1const request: IdentityVerificationCreateRequest = {
2  is_shareable: true,
3  template_id: 'idv_52xR9LKo77r1Np',
4  gave_consent: true,
5  user: {
6    client_user_id: 'user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d',
7    email_address: 'acharleston@email.com',
8    phone_number: '+11234567890',
9    date_of_birth: '1975-01-18',
10    name: {
11      given_name: 'Anna',
12      family_name: 'Charleston',
13    },
14    address: {
15      street: '100 Market Street',
16      street2: 'Apt 1A',
17      city: 'San Francisco',
18      region: 'CA',
19      postal_code: '94103',
20      country: 'US',
21    },
22    id_number: {
23      value: '123456789',
24      type: 'us_ssn',
25    },
26  },
27};
28try {
29  const response = await client.identityVerificationCreate(request);
30} catch (error) {
31  // handle error
32}
identity_verification/create

Response fields and example

id
string
ID of the associated Identity Verification attempt.
client_user_id
string
An identifier to help you connect this object to your internal systems. For example, your database ID corresponding to this object.

Min length: 1
created_at
string
An ISO8601 formatted timestamp.

Format: date-time
completed_at
nullablestring
An ISO8601 formatted timestamp.

Format: date-time
previous_attempt_id
nullablestring
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_url
nullablestring
A shareable URL that can be sent directly to the user to complete verification
template
object
The resource ID and version number of the template configuring the behavior of a given identity verification.
id
string
ID of the associated Identity Verification template.
version
number
Version of the associated Identity Verification template.
user
object
The identity data that was either collected from the user or provided via API in order to perform an identity verification.
phone_number
nullablestring
A phone number in E.164 format.
date_of_birth
nullablestring
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

Format: date
ip_address
nullablestring
An IPv4 or IPV6 address.
email_address
nullablestring
A valid email address.

Format: email
name
nullableobject
The full name provided by the user. If the user has not submitted their name, this field will be null. Otherwise, both fields are guaranteed to be filled.
given_name
string
A string with at least one non-whitespace character, with a max length of 100 characters.
family_name
string
A string with at least one non-whitespace character, with a max length of 100 characters.
address
nullableobject
Even if an address has been collected, some fields may be null depending on the region's addressing system. For example:
Addresses from the United Kingdom will not include a region
Addresses from Hong Kong will not include postal code
street
nullablestring
The primary street portion of an address. If the user has submitted their address, this field will always be filled.
street2
nullablestring
Extra street information, like an apartment or suite number.
city
nullablestring
City from the end user's address
region
nullablestring
An ISO 3166-2 subdivision code. Related terms would be "state", "province", "prefecture", "zone", "subdivision", etc.
postal_code
nullablestring
The postal code for the associated address. Between 2 and 10 alphanumeric characters. For US-based addresses this must be 5 numeric digits.
country
string
Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

Min length: 2
id_number
nullableobject
ID number submitted by the user, currently used only for the Identity Verification product. If the user has not submitted this data yet, this field will be null. Otherwise, both fields are guaranteed to be filled.
value
string
Value of identity document value typed in by user. Alpha-numeric, with all formatting characters stripped.
type
string
A globally unique and human readable ID type, specific to the country and document category. For more context on this field, see Hybrid Input Validation.

Possible values: ar_dni, au_drivers_license, au_passport, br_cpf, ca_sin, cl_run, cn_resident_card, co_nit, dk_cpr, eg_national_id, es_dni, es_nie, hk_hkid, in_pan, it_cf, jo_civil_id, jp_my_number, ke_huduma_namba, kw_civil_id, mx_curp, mx_rfc, my_nric, ng_nin, nz_drivers_license, om_civil_id, ph_psn, pl_pesel, ro_cnp, sa_national_id, se_pin, sg_nric, tr_tc_kimlik, us_ssn, us_ssn_last_4, za_smart_id
status
string
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 more than 48 hours without being completed and was automatically marked as expired.
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.

Possible values: active, success, failed, expired, canceled, pending_review
steps
object
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 call the user to fail the session as a whole, or cause them to fallback 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.
accept_tos
string
The status of a step in the identity verification process.

Possible values: success, active, failed, waiting_for_prerequisite, not_applicable, skipped, expired, canceled, pending_review, manually_approved, manually_rejected
verify_sms
string
The status of a step in the identity verification process.

Possible values: success, active, failed, waiting_for_prerequisite, not_applicable, skipped, expired, canceled, pending_review, manually_approved, manually_rejected
kyc_check
string
The status of a step in the identity verification process.

Possible values: success, active, failed, waiting_for_prerequisite, not_applicable, skipped, expired, canceled, pending_review, manually_approved, manually_rejected
documentary_verification
string
The status of a step in the identity verification process.

Possible values: success, active, failed, waiting_for_prerequisite, not_applicable, skipped, expired, canceled, pending_review, manually_approved, manually_rejected
selfie_check
string
The status of a step in the identity verification process.

Possible values: success, active, failed, waiting_for_prerequisite, not_applicable, skipped, expired, canceled, pending_review, manually_approved, manually_rejected
watchlist_screening
string
The status of a step in the identity verification process.

Possible values: success, active, failed, waiting_for_prerequisite, not_applicable, skipped, expired, canceled, pending_review, manually_approved, manually_rejected
risk_check
string
The status of a step in the identity verification process.

Possible values: success, active, failed, waiting_for_prerequisite, not_applicable, skipped, expired, canceled, pending_review, manually_approved, manually_rejected
documentary_verification
nullableobject
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.
status
string
The outcome status for the associated Identity Verification attempt's documentary_verification step. This field will always have the same value as steps.documentary_verification.
documents
[object]
An array of documents submitted to the documentary_verification step. Each entry represents one user submission, where each submission will contain both a front and back image, or just a front image, depending on the document type.
Note: Plaid will automatically let a user submit a new set of document images up to three times if we detect that a previous attempt might have failed due to user error. For example, if the first set of document images are blurry or obscured by glare, the user will be asked to capture their documents again, resulting in at least two separate entries within documents. If the overall documentary_verification is failed, the user has exhausted their retry attempts.
status
string
An outcome status for this specific document submission. Distinct from the overall documentary_verification.status that summarizes the verification outcome from one or more documents.

Possible values: success, failed, manually_approved
attempt
number
The attempt field begins with 1 and increments with each subsequent document upload.
images
object
URLs for downloading original and cropped images for this document submission. The URLs are designed to only allow downloading, not hot linking, so the URL will only serve the document image for 60 seconds before expiring. The expiration time is 60 seconds after the GET request for the associated Identity Verification attempt. A new expiring URL is generated with each request, so you can always rerequest the Identity Verification attempt if one of your URLs expires.
original_front
string
Temporary URL that expires after 60 seconds for downloading the uncropped original image of the front of the document.
original_back
nullablestring
Temporary URL that expires after 60 seconds for downloading the original image of the back of the document. Might be null if the back of the document was not collected.
cropped_front
nullablestring
Temporary URL that expires after 60 seconds for downloading a cropped image containing just the front of the document.
cropped_back
nullablestring
Temporary URL that expires after 60 seconds for downloading a cropped image containing just the back of the document. Might be null if the back of the document was not collected.
face
nullablestring
Temporary URL that expires after 60 seconds for downloading a crop of just the user's face from the document image. Might be null if the document does not contain a face photo.
extracted_data
nullableobject
Data extracted from a user-submitted document.
id_number
nullablestring
Alpha-numeric ID number extracted via OCR from the user's document image.
category
string
The type of identity document detected in the images provided. Will always be one of the following values:
drivers_license - A driver's license for the associated country
id_card - A general national identification card, distinct from driver's licenses
passport - A passport for the associated country
residence_permit_card - An identity document permitting a foreign citizen to temporarily reside in the associated country
resident_card - An identity document permitting a foreign citizen to permanently reside in the associated country
Note: This value may be different from the ID type that the user selects within Link. For example, if they select "Driver's License" but then submit a picture of a passport, this field will say passport

Possible values: drivers_license, id_card, passport, residence_permit_card, resident_card
expiration_date
nullablestring
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

Format: date
issuing_country
string
Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

Min length: 2
issuing_region
nullablestring
An ISO 3166-2 subdivision code. Related terms would be "state", "province", "prefecture", "zone", "subdivision", etc.
analysis
object
High level descriptions of how the associated document was processed. If a document fails verification, the details in the analysis object should help clarify why the document was rejected.
authenticity
string
High level summary of whether the document in the provided image matches the formatting rules and security checks for the associated jurisdiction.
For example, most identity documents have formatting rules like the following:
The image of the person's face must have a certain contrast in order to highlight skin tone
The subject in the document's image must remove eye glasses and pose in a certain way
The informational fields (name, date of birth, ID number, etc.) must be colored and aligned according to specific rules
Security features like watermarks and background patterns must be present
So a match status for this field indicates that the document in the provided image seems to conform to the various formatting and security rules associated with the detected document.

Possible values: match, partial_match, no_match, no_data
image_quality
string
A high level description of the quality of the image the user submitted.
For example, an image that is blurry, distorted by glare from a nearby light source, or improperly framed might be marked as low or medium quality. Poor quality images are more likely to fail OCR and/or template conformity checks.
Note: By default, Plaid will let a user recapture document images twice before failing the entire session if we attribute the failure to low image quality.

Possible values: high, medium, low
extracted_data
nullableobject
Analysis of the data extracted from the submitted document.
name
string
A match summary describing the cross comparison between the subject's name, extracted from the document image, and the name they separately provided to identity verification attempt.

Possible values: match, partial_match, no_match
date_of_birth
string
A match summary describing the cross comparison between the subject's date of birth, extracted from the document image, and the date of birth they separately provided to the identity verification attempt.

Possible values: match, partial_match, no_match
expiration_date
string
A description of whether the associated document was expired when the verification was performed.
Note: In the case where an expiration date is not present on the document or failed to be extracted, this value will be no_data.

Possible values: not_expired, expired, no_data
issuing_country
string
A binary match indicator specifying whether the country that issued the provided document matches the country that the user separately provided to Plaid.
Note: You can configure whether a no_match on issuing_country fails the documentary_verification by editing your Plaid Template.

Possible values: match, no_match
kyc_check
nullableobject
Additional information for the kyc_check step. This field will be null unless steps.kyc_check has reached a terminal state of either success or failed.
status
string
The outcome status for the associated Identity Verification attempt's kyc_check step. This field will always have the same value as steps.kyc_check.
address
object
Result summary object specifying how the address field matched.
summary
string
An enum indicating the match type between data provided by user and data checked against an external data source.
match indicates that the provided input data was a strong match against external data.
partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
no_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data.
no_data indicates that Plaid was unable to find external data to compare against the provided input data.
no_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user.

Possible values: match, partial_match, no_match, no_data, no_input
po_box
string
Field describing whether the associated address is a post office box. Will be yes when a P.O. box is detected, no when Plaid confirmed the address is not a P.O. box, and no_data when Plaid was not able to determine if the address is a P.O. box.

Possible values: yes, no, no_data
type
string
Field describing whether the associated address is being used for commercial or residential purposes.
Note: This value will be no_data when Plaid does not have sufficient data to determine the address's use.

Possible values: residential, commercial, no_data
name
object
Result summary object specifying how the name field matched.
summary
string
An enum indicating the match type between data provided by user and data checked against an external data source.
match indicates that the provided input data was a strong match against external data.
partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
no_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data.
no_data indicates that Plaid was unable to find external data to compare against the provided input data.
no_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user.

Possible values: match, partial_match, no_match, no_data, no_input
date_of_birth
object
Result summary object specifying how the date_of_birth field matched.
summary
string
An enum indicating the match type between data provided by user and data checked against an external data source.
match indicates that the provided input data was a strong match against external data.
partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
no_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data.
no_data indicates that Plaid was unable to find external data to compare against the provided input data.
no_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user.

Possible values: match, partial_match, no_match, no_data, no_input
id_number
object
Result summary object specifying how the id_number field matched.
summary
string
An enum indicating the match type between data provided by user and data checked against an external data source.
match indicates that the provided input data was a strong match against external data.
partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
no_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data.
no_data indicates that Plaid was unable to find external data to compare against the provided input data.
no_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user.

Possible values: match, partial_match, no_match, no_data, no_input
phone_number
object
Result summary object specifying how the phone field matched.
summary
string
An enum indicating the match type between data provided by user and data checked against an external data source.
match indicates that the provided input data was a strong match against external data.
partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
no_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data.
no_data indicates that Plaid was unable to find external data to compare against the provided input data.
no_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user.

Possible values: match, partial_match, no_match, no_data, no_input
watchlist_screening_id
nullablestring
ID of the associated screening.
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "id": "idv_52xR9LKo77r1Np",
3  "client_user_id": "your-db-id-3b24110",
4  "created_at": "2020-07-24T03:26:02Z",
5  "completed_at": "2020-07-24T03:26:02Z",
6  "previous_attempt_id": "idv_42cF1MNo42r9Xj",
7  "shareable_url": "https://flow.plaid.com/verify/idv_4FrXJvfQU3zGUR?key=e004115db797f7cc3083bff3167cba30644ef630fb46f5b086cde6cc3b86a36f",
8  "template": {
9    "id": "idvtmp_4FrXJvfQU3zGUR",
10    "version": 2
11  },
12  "user": {
13    "phone_number": "+19876543212",
14    "date_of_birth": "1990-05-29",
15    "ip_address": "192.0.2.42",
16    "email_address": "user@example.com",
17    "name": {
18      "given_name": "Leslie",
19      "family_name": "Knope"
20    },
21    "address": {
22      "street": "123 Main St.",
23      "street2": "Unit 42",
24      "city": "Pawnee",
25      "region": "IN",
26      "postal_code": "46001",
27      "country": "US"
28    },
29    "id_number": {
30      "value": "123456789",
31      "type": "us_ssn"
32    }
33  },
34  "status": "success",
35  "steps": {
36    "accept_tos": "success",
37    "verify_sms": "success",
38    "kyc_check": "success",
39    "documentary_verification": "success",
40    "selfie_check": "success",
41    "watchlist_screening": "success",
42    "risk_check": "success"
43  },
44  "documentary_verification": {
45    "status": "success",
46    "documents": [
47      {
48        "status": "success",
49        "attempt": 1,
50        "images": {
51          "original_front": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/original_front.jpeg",
52          "original_back": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/original_back.jpeg",
53          "cropped_front": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/cropped_front.jpeg",
54          "cropped_back": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/cropped_back.jpeg",
55          "face": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/face.jpeg"
56        },
57        "extracted_data": {
58          "id_number": "AB123456",
59          "category": "drivers_license",
60          "expiration_date": "1990-05-29",
61          "issuing_country": "US",
62          "issuing_region": "IN"
63        },
64        "analysis": {
65          "authenticity": "match",
66          "image_quality": "high",
67          "extracted_data": {
68            "name": "match",
69            "date_of_birth": "match",
70            "expiration_date": "not_expired",
71            "issuing_country": "match"
72          }
73        }
74      }
75    ]
76  },
77  "kyc_check": {
78    "status": "success",
79    "address": {
80      "summary": "match",
81      "po_box": "yes",
82      "type": "residential"
83    },
84    "name": {
85      "summary": "match"
86    },
87    "date_of_birth": {
88      "summary": "match"
89    },
90    "id_number": {
91      "summary": "match"
92    },
93    "phone_number": {
94      "summary": "match"
95    }
96  },
97  "watchlist_screening_id": "scr_52xR9LKo77r1Np",
98  "request_id": "saKrIBuEB9qJZng"
99}

/identity_verification/get

Retrieve Identity Verification

Retrieve a previously created identity verification.

identity_verification/get

Request fields and example

identity_verification_id
requiredstring
ID of the associated Identity Verification attempt.
secret
string
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_id
string
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.
1const request: IdentityVerificationGetRequest = {
2  identity_verification_id: 'idv_52xR9LKo77r1Np',
3};
4try {
5  const response = await plaidClient.identityVerificationGet(request);
6} catch (error) {
7  // handle error
8}
identity_verification/get

Response fields and example

id
string
ID of the associated Identity Verification attempt.
client_user_id
string
An identifier to help you connect this object to your internal systems. For example, your database ID corresponding to this object.

Min length: 1
created_at
string
An ISO8601 formatted timestamp.

Format: date-time
completed_at
nullablestring
An ISO8601 formatted timestamp.

Format: date-time
previous_attempt_id
nullablestring
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_url
nullablestring
A shareable URL that can be sent directly to the user to complete verification
template
object
The resource ID and version number of the template configuring the behavior of a given identity verification.
id
string
ID of the associated Identity Verification template.
version
number
Version of the associated Identity Verification template.
user
object
The identity data that was either collected from the user or provided via API in order to perform an identity verification.
phone_number
nullablestring
A phone number in E.164 format.
date_of_birth
nullablestring
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

Format: date
ip_address
nullablestring
An IPv4 or IPV6 address.
email_address
nullablestring
A valid email address.

Format: email
name
nullableobject
The full name provided by the user. If the user has not submitted their name, this field will be null. Otherwise, both fields are guaranteed to be filled.
given_name
string
A string with at least one non-whitespace character, with a max length of 100 characters.
family_name
string
A string with at least one non-whitespace character, with a max length of 100 characters.
address
nullableobject
Even if an address has been collected, some fields may be null depending on the region's addressing system. For example:
Addresses from the United Kingdom will not include a region
Addresses from Hong Kong will not include postal code
street
nullablestring
The primary street portion of an address. If the user has submitted their address, this field will always be filled.
street2
nullablestring
Extra street information, like an apartment or suite number.
city
nullablestring
City from the end user's address
region
nullablestring
An ISO 3166-2 subdivision code. Related terms would be "state", "province", "prefecture", "zone", "subdivision", etc.
postal_code
nullablestring
The postal code for the associated address. Between 2 and 10 alphanumeric characters. For US-based addresses this must be 5 numeric digits.
country
string
Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

Min length: 2
id_number
nullableobject
ID number submitted by the user, currently used only for the Identity Verification product. If the user has not submitted this data yet, this field will be null. Otherwise, both fields are guaranteed to be filled.
value
string
Value of identity document value typed in by user. Alpha-numeric, with all formatting characters stripped.
type
string
A globally unique and human readable ID type, specific to the country and document category. For more context on this field, see Hybrid Input Validation.

Possible values: ar_dni, au_drivers_license, au_passport, br_cpf, ca_sin, cl_run, cn_resident_card, co_nit, dk_cpr, eg_national_id, es_dni, es_nie, hk_hkid, in_pan, it_cf, jo_civil_id, jp_my_number, ke_huduma_namba, kw_civil_id, mx_curp, mx_rfc, my_nric, ng_nin, nz_drivers_license, om_civil_id, ph_psn, pl_pesel, ro_cnp, sa_national_id, se_pin, sg_nric, tr_tc_kimlik, us_ssn, us_ssn_last_4, za_smart_id
status
string
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 more than 48 hours without being completed and was automatically marked as expired.
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.

Possible values: active, success, failed, expired, canceled, pending_review
steps
object
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 call the user to fail the session as a whole, or cause them to fallback 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.
accept_tos
string
The status of a step in the identity verification process.

Possible values: success, active, failed, waiting_for_prerequisite, not_applicable, skipped, expired, canceled, pending_review, manually_approved, manually_rejected
verify_sms
string
The status of a step in the identity verification process.

Possible values: success, active, failed, waiting_for_prerequisite, not_applicable, skipped, expired, canceled, pending_review, manually_approved, manually_rejected
kyc_check
string
The status of a step in the identity verification process.

Possible values: success, active, failed, waiting_for_prerequisite, not_applicable, skipped, expired, canceled, pending_review, manually_approved, manually_rejected
documentary_verification
string
The status of a step in the identity verification process.

Possible values: success, active, failed, waiting_for_prerequisite, not_applicable, skipped, expired, canceled, pending_review, manually_approved, manually_rejected
selfie_check
string
The status of a step in the identity verification process.

Possible values: success, active, failed, waiting_for_prerequisite, not_applicable, skipped, expired, canceled, pending_review, manually_approved, manually_rejected
watchlist_screening
string
The status of a step in the identity verification process.

Possible values: success, active, failed, waiting_for_prerequisite, not_applicable, skipped, expired, canceled, pending_review, manually_approved, manually_rejected
risk_check
string
The status of a step in the identity verification process.

Possible values: success, active, failed, waiting_for_prerequisite, not_applicable, skipped, expired, canceled, pending_review, manually_approved, manually_rejected
documentary_verification
nullableobject
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.
status
string
The outcome status for the associated Identity Verification attempt's documentary_verification step. This field will always have the same value as steps.documentary_verification.
documents
[object]
An array of documents submitted to the documentary_verification step. Each entry represents one user submission, where each submission will contain both a front and back image, or just a front image, depending on the document type.
Note: Plaid will automatically let a user submit a new set of document images up to three times if we detect that a previous attempt might have failed due to user error. For example, if the first set of document images are blurry or obscured by glare, the user will be asked to capture their documents again, resulting in at least two separate entries within documents. If the overall documentary_verification is failed, the user has exhausted their retry attempts.
status
string
An outcome status for this specific document submission. Distinct from the overall documentary_verification.status that summarizes the verification outcome from one or more documents.

Possible values: success, failed, manually_approved
attempt
number
The attempt field begins with 1 and increments with each subsequent document upload.
images
object
URLs for downloading original and cropped images for this document submission. The URLs are designed to only allow downloading, not hot linking, so the URL will only serve the document image for 60 seconds before expiring. The expiration time is 60 seconds after the GET request for the associated Identity Verification attempt. A new expiring URL is generated with each request, so you can always rerequest the Identity Verification attempt if one of your URLs expires.
original_front
string
Temporary URL that expires after 60 seconds for downloading the uncropped original image of the front of the document.
original_back
nullablestring
Temporary URL that expires after 60 seconds for downloading the original image of the back of the document. Might be null if the back of the document was not collected.
cropped_front
nullablestring
Temporary URL that expires after 60 seconds for downloading a cropped image containing just the front of the document.
cropped_back
nullablestring
Temporary URL that expires after 60 seconds for downloading a cropped image containing just the back of the document. Might be null if the back of the document was not collected.
face
nullablestring
Temporary URL that expires after 60 seconds for downloading a crop of just the user's face from the document image. Might be null if the document does not contain a face photo.
extracted_data
nullableobject
Data extracted from a user-submitted document.
id_number
nullablestring
Alpha-numeric ID number extracted via OCR from the user's document image.
category
string
The type of identity document detected in the images provided. Will always be one of the following values:
drivers_license - A driver's license for the associated country
id_card - A general national identification card, distinct from driver's licenses
passport - A passport for the associated country
residence_permit_card - An identity document permitting a foreign citizen to temporarily reside in the associated country
resident_card - An identity document permitting a foreign citizen to permanently reside in the associated country
Note: This value may be different from the ID type that the user selects within Link. For example, if they select "Driver's License" but then submit a picture of a passport, this field will say passport

Possible values: drivers_license, id_card, passport, residence_permit_card, resident_card
expiration_date
nullablestring
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

Format: date
issuing_country
string
Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

Min length: 2
issuing_region
nullablestring
An ISO 3166-2 subdivision code. Related terms would be "state", "province", "prefecture", "zone", "subdivision", etc.
analysis
object
High level descriptions of how the associated document was processed. If a document fails verification, the details in the analysis object should help clarify why the document was rejected.
authenticity
string
High level summary of whether the document in the provided image matches the formatting rules and security checks for the associated jurisdiction.
For example, most identity documents have formatting rules like the following:
The image of the person's face must have a certain contrast in order to highlight skin tone
The subject in the document's image must remove eye glasses and pose in a certain way
The informational fields (name, date of birth, ID number, etc.) must be colored and aligned according to specific rules
Security features like watermarks and background patterns must be present
So a match status for this field indicates that the document in the provided image seems to conform to the various formatting and security rules associated with the detected document.

Possible values: match, partial_match, no_match, no_data
image_quality
string
A high level description of the quality of the image the user submitted.
For example, an image that is blurry, distorted by glare from a nearby light source, or improperly framed might be marked as low or medium quality. Poor quality images are more likely to fail OCR and/or template conformity checks.
Note: By default, Plaid will let a user recapture document images twice before failing the entire session if we attribute the failure to low image quality.

Possible values: high, medium, low
extracted_data
nullableobject
Analysis of the data extracted from the submitted document.
name
string
A match summary describing the cross comparison between the subject's name, extracted from the document image, and the name they separately provided to identity verification attempt.

Possible values: match, partial_match, no_match
date_of_birth
string
A match summary describing the cross comparison between the subject's date of birth, extracted from the document image, and the date of birth they separately provided to the identity verification attempt.

Possible values: match, partial_match, no_match
expiration_date
string
A description of whether the associated document was expired when the verification was performed.
Note: In the case where an expiration date is not present on the document or failed to be extracted, this value will be no_data.

Possible values: not_expired, expired, no_data
issuing_country
string
A binary match indicator specifying whether the country that issued the provided document matches the country that the user separately provided to Plaid.
Note: You can configure whether a no_match on issuing_country fails the documentary_verification by editing your Plaid Template.

Possible values: match, no_match
kyc_check
nullableobject
Additional information for the kyc_check step. This field will be null unless steps.kyc_check has reached a terminal state of either success or failed.
status
string
The outcome status for the associated Identity Verification attempt's kyc_check step. This field will always have the same value as steps.kyc_check.
address
object
Result summary object specifying how the address field matched.
summary
string
An enum indicating the match type between data provided by user and data checked against an external data source.
match indicates that the provided input data was a strong match against external data.
partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
no_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data.
no_data indicates that Plaid was unable to find external data to compare against the provided input data.
no_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user.

Possible values: match, partial_match, no_match, no_data, no_input
po_box
string
Field describing whether the associated address is a post office box. Will be yes when a P.O. box is detected, no when Plaid confirmed the address is not a P.O. box, and no_data when Plaid was not able to determine if the address is a P.O. box.

Possible values: yes, no, no_data
type
string
Field describing whether the associated address is being used for commercial or residential purposes.
Note: This value will be no_data when Plaid does not have sufficient data to determine the address's use.

Possible values: residential, commercial, no_data
name
object
Result summary object specifying how the name field matched.
summary
string
An enum indicating the match type between data provided by user and data checked against an external data source.
match indicates that the provided input data was a strong match against external data.
partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
no_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data.
no_data indicates that Plaid was unable to find external data to compare against the provided input data.
no_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user.

Possible values: match, partial_match, no_match, no_data, no_input
date_of_birth
object
Result summary object specifying how the date_of_birth field matched.
summary
string
An enum indicating the match type between data provided by user and data checked against an external data source.
match indicates that the provided input data was a strong match against external data.
partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
no_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data.
no_data indicates that Plaid was unable to find external data to compare against the provided input data.
no_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user.

Possible values: match, partial_match, no_match, no_data, no_input
id_number
object
Result summary object specifying how the id_number field matched.
summary
string
An enum indicating the match type between data provided by user and data checked against an external data source.
match indicates that the provided input data was a strong match against external data.
partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
no_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data.
no_data indicates that Plaid was unable to find external data to compare against the provided input data.
no_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user.

Possible values: match, partial_match, no_match, no_data, no_input
phone_number
object
Result summary object specifying how the phone field matched.
summary
string
An enum indicating the match type between data provided by user and data checked against an external data source.
match indicates that the provided input data was a strong match against external data.
partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
no_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data.
no_data indicates that Plaid was unable to find external data to compare against the provided input data.
no_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user.

Possible values: match, partial_match, no_match, no_data, no_input
watchlist_screening_id
nullablestring
ID of the associated screening.
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "id": "idv_52xR9LKo77r1Np",
3  "client_user_id": "your-db-id-3b24110",
4  "created_at": "2020-07-24T03:26:02Z",
5  "completed_at": "2020-07-24T03:26:02Z",
6  "previous_attempt_id": "idv_42cF1MNo42r9Xj",
7  "shareable_url": "https://flow.plaid.com/verify/idv_4FrXJvfQU3zGUR?key=e004115db797f7cc3083bff3167cba30644ef630fb46f5b086cde6cc3b86a36f",
8  "template": {
9    "id": "idvtmp_4FrXJvfQU3zGUR",
10    "version": 2
11  },
12  "user": {
13    "phone_number": "+19876543212",
14    "date_of_birth": "1990-05-29",
15    "ip_address": "192.0.2.42",
16    "email_address": "user@example.com",
17    "name": {
18      "given_name": "Leslie",
19      "family_name": "Knope"
20    },
21    "address": {
22      "street": "123 Main St.",
23      "street2": "Unit 42",
24      "city": "Pawnee",
25      "region": "IN",
26      "postal_code": "46001",
27      "country": "US"
28    },
29    "id_number": {
30      "value": "123456789",
31      "type": "us_ssn"
32    }
33  },
34  "status": "success",
35  "steps": {
36    "accept_tos": "success",
37    "verify_sms": "success",
38    "kyc_check": "success",
39    "documentary_verification": "success",
40    "selfie_check": "success",
41    "watchlist_screening": "success",
42    "risk_check": "success"
43  },
44  "documentary_verification": {
45    "status": "success",
46    "documents": [
47      {
48        "status": "success",
49        "attempt": 1,
50        "images": {
51          "original_front": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/original_front.jpeg",
52          "original_back": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/original_back.jpeg",
53          "cropped_front": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/cropped_front.jpeg",
54          "cropped_back": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/cropped_back.jpeg",
55          "face": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/face.jpeg"
56        },
57        "extracted_data": {
58          "id_number": "AB123456",
59          "category": "drivers_license",
60          "expiration_date": "1990-05-29",
61          "issuing_country": "US",
62          "issuing_region": "IN"
63        },
64        "analysis": {
65          "authenticity": "match",
66          "image_quality": "high",
67          "extracted_data": {
68            "name": "match",
69            "date_of_birth": "match",
70            "expiration_date": "not_expired",
71            "issuing_country": "match"
72          }
73        }
74      }
75    ]
76  },
77  "kyc_check": {
78    "status": "success",
79    "address": {
80      "summary": "match",
81      "po_box": "yes",
82      "type": "residential"
83    },
84    "name": {
85      "summary": "match"
86    },
87    "date_of_birth": {
88      "summary": "match"
89    },
90    "id_number": {
91      "summary": "match"
92    },
93    "phone_number": {
94      "summary": "match"
95    }
96  },
97  "watchlist_screening_id": "scr_52xR9LKo77r1Np",
98  "request_id": "saKrIBuEB9qJZng"
99}

/identity_verification/list

List Identity Verifications

Filter and list Identity Verifications created by your account

identity_verification/list

Request fields and example

secret
string
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_id
string
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.
template_id
requiredstring
ID of the associated Identity Verification template.
client_user_id
requiredstring
An identifier to help you connect this object to your internal systems. For example, your database ID corresponding to this object.

Min length: 1
cursor
string
An identifier that determines which page of results you receive.
1const request: ListIdentityVerificationRequest = {
2  template_id: 'idv_52xR9LKo77r1Np',
3  client_user_id: 'user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d',
4};
5try {
6  const response = await plaidClient.identityVerificationList(request);
7} catch (error) {
8  // handle error
9}
identity_verification/list

Response fields and example

identity_verifications
[object]
List of Plaid sessions
id
string
ID of the associated Identity Verification attempt.
client_user_id
string
An identifier to help you connect this object to your internal systems. For example, your database ID corresponding to this object.

Min length: 1
created_at
string
An ISO8601 formatted timestamp.

Format: date-time
completed_at
nullablestring
An ISO8601 formatted timestamp.

Format: date-time
previous_attempt_id
nullablestring
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_url
nullablestring
A shareable URL that can be sent directly to the user to complete verification
template
object
The resource ID and version number of the template configuring the behavior of a given identity verification.
id
string
ID of the associated Identity Verification template.
version
number
Version of the associated Identity Verification template.
user
object
The identity data that was either collected from the user or provided via API in order to perform an identity verification.
phone_number
nullablestring
A phone number in E.164 format.
date_of_birth
nullablestring
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

Format: date
ip_address
nullablestring
An IPv4 or IPV6 address.
email_address
nullablestring
A valid email address.

Format: email
name
nullableobject
The full name provided by the user. If the user has not submitted their name, this field will be null. Otherwise, both fields are guaranteed to be filled.
given_name
string
A string with at least one non-whitespace character, with a max length of 100 characters.
family_name
string
A string with at least one non-whitespace character, with a max length of 100 characters.
address
nullableobject
Even if an address has been collected, some fields may be null depending on the region's addressing system. For example:
Addresses from the United Kingdom will not include a region
Addresses from Hong Kong will not include postal code
street
nullablestring
The primary street portion of an address. If the user has submitted their address, this field will always be filled.
street2
nullablestring
Extra street information, like an apartment or suite number.
city
nullablestring
City from the end user's address
region
nullablestring
An ISO 3166-2 subdivision code. Related terms would be "state", "province", "prefecture", "zone", "subdivision", etc.
postal_code
nullablestring
The postal code for the associated address. Between 2 and 10 alphanumeric characters. For US-based addresses this must be 5 numeric digits.
country
string
Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

Min length: 2
id_number
nullableobject
ID number submitted by the user, currently used only for the Identity Verification product. If the user has not submitted this data yet, this field will be null. Otherwise, both fields are guaranteed to be filled.
value
string
Value of identity document value typed in by user. Alpha-numeric, with all formatting characters stripped.
type
string
A globally unique and human readable ID type, specific to the country and document category. For more context on this field, see Hybrid Input Validation.

Possible values: ar_dni, au_drivers_license, au_passport, br_cpf, ca_sin, cl_run, cn_resident_card, co_nit, dk_cpr, eg_national_id, es_dni, es_nie, hk_hkid, in_pan, it_cf, jo_civil_id, jp_my_number, ke_huduma_namba, kw_civil_id, mx_curp, mx_rfc, my_nric, ng_nin, nz_drivers_license, om_civil_id, ph_psn, pl_pesel, ro_cnp, sa_national_id, se_pin, sg_nric, tr_tc_kimlik, us_ssn, us_ssn_last_4, za_smart_id
status
string
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 more than 48 hours without being completed and was automatically marked as expired.
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.

Possible values: active, success, failed, expired, canceled, pending_review
steps
object
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 call the user to fail the session as a whole, or cause them to fallback 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.
accept_tos
string
The status of a step in the identity verification process.

Possible values: success, active, failed, waiting_for_prerequisite, not_applicable, skipped, expired, canceled, pending_review, manually_approved, manually_rejected
verify_sms
string
The status of a step in the identity verification process.

Possible values: success, active, failed, waiting_for_prerequisite, not_applicable, skipped, expired, canceled, pending_review, manually_approved, manually_rejected
kyc_check
string
The status of a step in the identity verification process.

Possible values: success, active, failed, waiting_for_prerequisite, not_applicable, skipped, expired, canceled, pending_review, manually_approved, manually_rejected
documentary_verification
string
The status of a step in the identity verification process.

Possible values: success, active, failed, waiting_for_prerequisite, not_applicable, skipped, expired, canceled, pending_review, manually_approved, manually_rejected
selfie_check
string
The status of a step in the identity verification process.

Possible values: success, active, failed, waiting_for_prerequisite, not_applicable, skipped, expired, canceled, pending_review, manually_approved, manually_rejected
watchlist_screening
string
The status of a step in the identity verification process.

Possible values: success, active, failed, waiting_for_prerequisite, not_applicable, skipped, expired, canceled, pending_review, manually_approved, manually_rejected
risk_check
string
The status of a step in the identity verification process.

Possible values: success, active, failed, waiting_for_prerequisite, not_applicable, skipped, expired, canceled, pending_review, manually_approved, manually_rejected
documentary_verification
nullableobject
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.
status
string
The outcome status for the associated Identity Verification attempt's documentary_verification step. This field will always have the same value as steps.documentary_verification.
documents
[object]
An array of documents submitted to the documentary_verification step. Each entry represents one user submission, where each submission will contain both a front and back image, or just a front image, depending on the document type.
Note: Plaid will automatically let a user submit a new set of document images up to three times if we detect that a previous attempt might have failed due to user error. For example, if the first set of document images are blurry or obscured by glare, the user will be asked to capture their documents again, resulting in at least two separate entries within documents. If the overall documentary_verification is failed, the user has exhausted their retry attempts.
status
string
An outcome status for this specific document submission. Distinct from the overall documentary_verification.status that summarizes the verification outcome from one or more documents.

Possible values: success, failed, manually_approved
attempt
number
The attempt field begins with 1 and increments with each subsequent document upload.
images
object
URLs for downloading original and cropped images for this document submission. The URLs are designed to only allow downloading, not hot linking, so the URL will only serve the document image for 60 seconds before expiring. The expiration time is 60 seconds after the GET request for the associated Identity Verification attempt. A new expiring URL is generated with each request, so you can always rerequest the Identity Verification attempt if one of your URLs expires.
original_front
string
Temporary URL that expires after 60 seconds for downloading the uncropped original image of the front of the document.
original_back
nullablestring
Temporary URL that expires after 60 seconds for downloading the original image of the back of the document. Might be null if the back of the document was not collected.
cropped_front
nullablestring
Temporary URL that expires after 60 seconds for downloading a cropped image containing just the front of the document.
cropped_back
nullablestring
Temporary URL that expires after 60 seconds for downloading a cropped image containing just the back of the document. Might be null if the back of the document was not collected.
face
nullablestring
Temporary URL that expires after 60 seconds for downloading a crop of just the user's face from the document image. Might be null if the document does not contain a face photo.
extracted_data
nullableobject
Data extracted from a user-submitted document.
id_number
nullablestring
Alpha-numeric ID number extracted via OCR from the user's document image.
category
string
The type of identity document detected in the images provided. Will always be one of the following values:
drivers_license - A driver's license for the associated country
id_card - A general national identification card, distinct from driver's licenses
passport - A passport for the associated country
residence_permit_card - An identity document permitting a foreign citizen to temporarily reside in the associated country
resident_card - An identity document permitting a foreign citizen to permanently reside in the associated country
Note: This value may be different from the ID type that the user selects within Link. For example, if they select "Driver's License" but then submit a picture of a passport, this field will say passport

Possible values: drivers_license, id_card, passport, residence_permit_card, resident_card
expiration_date
nullablestring
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

Format: date
issuing_country
string
Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

Min length: 2
issuing_region
nullablestring
An ISO 3166-2 subdivision code. Related terms would be "state", "province", "prefecture", "zone", "subdivision", etc.
analysis
object
High level descriptions of how the associated document was processed. If a document fails verification, the details in the analysis object should help clarify why the document was rejected.
authenticity
string
High level summary of whether the document in the provided image matches the formatting rules and security checks for the associated jurisdiction.
For example, most identity documents have formatting rules like the following:
The image of the person's face must have a certain contrast in order to highlight skin tone
The subject in the document's image must remove eye glasses and pose in a certain way
The informational fields (name, date of birth, ID number, etc.) must be colored and aligned according to specific rules
Security features like watermarks and background patterns must be present
So a match status for this field indicates that the document in the provided image seems to conform to the various formatting and security rules associated with the detected document.

Possible values: match, partial_match, no_match, no_data
image_quality
string
A high level description of the quality of the image the user submitted.
For example, an image that is blurry, distorted by glare from a nearby light source, or improperly framed might be marked as low or medium quality. Poor quality images are more likely to fail OCR and/or template conformity checks.
Note: By default, Plaid will let a user recapture document images twice before failing the entire session if we attribute the failure to low image quality.

Possible values: high, medium, low
extracted_data
nullableobject
Analysis of the data extracted from the submitted document.
name
string
A match summary describing the cross comparison between the subject's name, extracted from the document image, and the name they separately provided to identity verification attempt.

Possible values: match, partial_match, no_match
date_of_birth
string
A match summary describing the cross comparison between the subject's date of birth, extracted from the document image, and the date of birth they separately provided to the identity verification attempt.

Possible values: match, partial_match, no_match
expiration_date
string
A description of whether the associated document was expired when the verification was performed.
Note: In the case where an expiration date is not present on the document or failed to be extracted, this value will be no_data.

Possible values: not_expired, expired, no_data
issuing_country
string
A binary match indicator specifying whether the country that issued the provided document matches the country that the user separately provided to Plaid.
Note: You can configure whether a no_match on issuing_country fails the documentary_verification by editing your Plaid Template.

Possible values: match, no_match
kyc_check
nullableobject
Additional information for the kyc_check step. This field will be null unless steps.kyc_check has reached a terminal state of either success or failed.
status
string
The outcome status for the associated Identity Verification attempt's kyc_check step. This field will always have the same value as steps.kyc_check.
address
object
Result summary object specifying how the address field matched.
summary
string
An enum indicating the match type between data provided by user and data checked against an external data source.
match indicates that the provided input data was a strong match against external data.
partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
no_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data.
no_data indicates that Plaid was unable to find external data to compare against the provided input data.
no_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user.

Possible values: match, partial_match, no_match, no_data, no_input
po_box
string
Field describing whether the associated address is a post office box. Will be yes when a P.O. box is detected, no when Plaid confirmed the address is not a P.O. box, and no_data when Plaid was not able to determine if the address is a P.O. box.

Possible values: yes, no, no_data
type
string
Field describing whether the associated address is being used for commercial or residential purposes.
Note: This value will be no_data when Plaid does not have sufficient data to determine the address's use.

Possible values: residential, commercial, no_data
name
object
Result summary object specifying how the name field matched.
summary
string
An enum indicating the match type between data provided by user and data checked against an external data source.
match indicates that the provided input data was a strong match against external data.
partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
no_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data.
no_data indicates that Plaid was unable to find external data to compare against the provided input data.
no_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user.

Possible values: match, partial_match, no_match, no_data, no_input
date_of_birth
object
Result summary object specifying how the date_of_birth field matched.
summary
string
An enum indicating the match type between data provided by user and data checked against an external data source.
match indicates that the provided input data was a strong match against external data.
partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
no_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data.
no_data indicates that Plaid was unable to find external data to compare against the provided input data.
no_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user.

Possible values: match, partial_match, no_match, no_data, no_input
id_number
object
Result summary object specifying how the id_number field matched.
summary
string
An enum indicating the match type between data provided by user and data checked against an external data source.
match indicates that the provided input data was a strong match against external data.
partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
no_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data.
no_data indicates that Plaid was unable to find external data to compare against the provided input data.
no_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user.

Possible values: match, partial_match, no_match, no_data, no_input
phone_number
object
Result summary object specifying how the phone field matched.
summary
string
An enum indicating the match type between data provided by user and data checked against an external data source.
match indicates that the provided input data was a strong match against external data.
partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
no_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data.
no_data indicates that Plaid was unable to find external data to compare against the provided input data.
no_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user.

Possible values: match, partial_match, no_match, no_data, no_input
watchlist_screening_id
nullablestring
ID of the associated screening.
next_cursor
nullablestring
An identifier that determines which page of results you receive.
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "identity_verifications": [
3    {
4      "id": "idv_52xR9LKo77r1Np",
5      "client_user_id": "your-db-id-3b24110",
6      "created_at": "2020-07-24T03:26:02Z",
7      "completed_at": "2020-07-24T03:26:02Z",
8      "previous_attempt_id": "idv_42cF1MNo42r9Xj",
9      "shareable_url": "https://flow.plaid.com/verify/idv_4FrXJvfQU3zGUR?key=e004115db797f7cc3083bff3167cba30644ef630fb46f5b086cde6cc3b86a36f",
10      "template": {
11        "id": "idvtmp_4FrXJvfQU3zGUR",
12        "version": 2
13      },
14      "user": {
15        "phone_number": "+19876543212",
16        "date_of_birth": "1990-05-29",
17        "ip_address": "192.0.2.42",
18        "email_address": "user@example.com",
19        "name": {
20          "given_name": "Leslie",
21          "family_name": "Knope"
22        },
23        "address": {
24          "street": "123 Main St.",
25          "street2": "Unit 42",
26          "city": "Pawnee",
27          "region": "IN",
28          "postal_code": "46001",
29          "country": "US"
30        },
31        "id_number": {
32          "value": "123456789",
33          "type": "us_ssn"
34        }
35      },
36      "status": "success",
37      "steps": {
38        "accept_tos": "success",
39        "verify_sms": "success",
40        "kyc_check": "success",
41        "documentary_verification": "success",
42        "selfie_check": "success",
43        "watchlist_screening": "success",
44        "risk_check": "success"
45      },
46      "documentary_verification": {
47        "status": "success",
48        "documents": [
49          {
50            "status": "success",
51            "attempt": 1,
52            "images": {
53              "original_front": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/original_front.jpeg",
54              "original_back": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/original_back.jpeg",
55              "cropped_front": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/cropped_front.jpeg",
56              "cropped_back": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/cropped_back.jpeg",
57              "face": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/face.jpeg"
58            },
59            "extracted_data": {
60              "id_number": "AB123456",
61              "category": "drivers_license",
62              "expiration_date": "1990-05-29",
63              "issuing_country": "US",
64              "issuing_region": "IN"
65            },
66            "analysis": {
67              "authenticity": "match",
68              "image_quality": "high",
69              "extracted_data": {
70                "name": "match",
71                "date_of_birth": "match",
72                "expiration_date": "not_expired",
73                "issuing_country": "match"
74              }
75            }
76          }
77        ]
78      },
79      "kyc_check": {
80        "status": "success",
81        "address": {
82          "summary": "match",
83          "po_box": "yes",
84          "type": "residential"
85        },
86        "name": {
87          "summary": "match"
88        },
89        "date_of_birth": {
90          "summary": "match"
91        },
92        "id_number": {
93          "summary": "match"
94        },
95        "phone_number": {
96          "summary": "match"
97        }
98      },
99      "watchlist_screening_id": "scr_52xR9LKo77r1Np"
100    }
101  ],
102  "next_cursor": "eyJkaXJlY3Rpb24iOiJuZXh0Iiwib2Zmc2V0IjoiMTU5NDM",
103  "request_id": "saKrIBuEB9qJZng"
104}

/identity_verification/retry

Retry an Identity Verification

Allow a customer to retry their identity verification

identity_verification/retry

Request fields and example

client_user_id
requiredstring
An identifier to help you connect this object to your internal systems. For example, your database ID corresponding to this object.

Min length: 1
template_id
requiredstring
ID of the associated Identity Verification template.
strategy
requiredstring
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 screening or risk_check.
The infer strategy cannot be applied if the session's status is still active

Possible values: reset, incomplete, infer, custom
steps
object
Instructions for the custom retry strategy specifying which steps should be required or skipped.
Note:
This field must be provided when the retry strategy is custom and must be omitted otherwise.
Custom retries override settings in your Plaid Template. For example, if your Plaid Template has verify_sms disabled, a custom retry with verify_sms enabled will still require the step.
The selfie_check step is currently not supported on the sandbox server. Sandbox requests will silently disable the selfie_check step when provided.
verify_sms
requiredboolean
A boolean field specifying whether the new session should require or skip the verify_sms step.
kyc_check
requiredboolean
A boolean field specifying whether the new session should require or skip the kyc_check step.
documentary_verification
requiredboolean
A boolean field specifying whether the new session should require or skip the documentary_verification step.
selfie_check
requiredboolean
A boolean field specifying whether the new session should require or skip the selfie_check step.
client_id
string
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.
secret
string
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.
1const request: IdentityVerificationRetryRequest = {
2  client_user_id: 'user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d',
3  template_id: 'idv_52xR9LKo77r1Np',
4  strategy: 'reset',
5};
6try {
7  const response = await plaidClient.identityVerificationRetry(request);
8} catch (error) {
9  // handle error
10}
identity_verification/retry

Response fields and example

id
string
ID of the associated Identity Verification attempt.
client_user_id
string
An identifier to help you connect this object to your internal systems. For example, your database ID corresponding to this object.

Min length: 1
created_at
string
An ISO8601 formatted timestamp.

Format: date-time
completed_at
nullablestring
An ISO8601 formatted timestamp.

Format: date-time
previous_attempt_id
nullablestring
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_url
nullablestring
A shareable URL that can be sent directly to the user to complete verification
template
object
The resource ID and version number of the template configuring the behavior of a given identity verification.
id
string
ID of the associated Identity Verification template.
version
number
Version of the associated Identity Verification template.
user
object
The identity data that was either collected from the user or provided via API in order to perform an identity verification.
phone_number
nullablestring
A phone number in E.164 format.
date_of_birth
nullablestring
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

Format: date
ip_address
nullablestring
An IPv4 or IPV6 address.
email_address
nullablestring
A valid email address.

Format: email
name
nullableobject
The full name provided by the user. If the user has not submitted their name, this field will be null. Otherwise, both fields are guaranteed to be filled.
given_name
string
A string with at least one non-whitespace character, with a max length of 100 characters.
family_name
string
A string with at least one non-whitespace character, with a max length of 100 characters.
address
nullableobject
Even if an address has been collected, some fields may be null depending on the region's addressing system. For example:
Addresses from the United Kingdom will not include a region
Addresses from Hong Kong will not include postal code
street
nullablestring
The primary street portion of an address. If the user has submitted their address, this field will always be filled.
street2
nullablestring
Extra street information, like an apartment or suite number.
city
nullablestring
City from the end user's address
region
nullablestring
An ISO 3166-2 subdivision code. Related terms would be "state", "province", "prefecture", "zone", "subdivision", etc.
postal_code
nullablestring
The postal code for the associated address. Between 2 and 10 alphanumeric characters. For US-based addresses this must be 5 numeric digits.
country
string
Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

Min length: 2
id_number
nullableobject
ID number submitted by the user, currently used only for the Identity Verification product. If the user has not submitted this data yet, this field will be null. Otherwise, both fields are guaranteed to be filled.
value
string
Value of identity document value typed in by user. Alpha-numeric, with all formatting characters stripped.
type
string
A globally unique and human readable ID type, specific to the country and document category. For more context on this field, see Hybrid Input Validation.

Possible values: ar_dni, au_drivers_license, au_passport, br_cpf, ca_sin, cl_run, cn_resident_card, co_nit, dk_cpr, eg_national_id, es_dni, es_nie, hk_hkid, in_pan, it_cf, jo_civil_id, jp_my_number, ke_huduma_namba, kw_civil_id, mx_curp, mx_rfc, my_nric, ng_nin, nz_drivers_license, om_civil_id, ph_psn, pl_pesel, ro_cnp, sa_national_id, se_pin, sg_nric, tr_tc_kimlik, us_ssn, us_ssn_last_4, za_smart_id
status
string
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 more than 48 hours without being completed and was automatically marked as expired.
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.

Possible values: active, success, failed, expired, canceled, pending_review
steps
object
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 call the user to fail the session as a whole, or cause them to fallback 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.
accept_tos
string
The status of a step in the identity verification process.

Possible values: success, active, failed, waiting_for_prerequisite, not_applicable, skipped, expired, canceled, pending_review, manually_approved, manually_rejected
verify_sms
string
The status of a step in the identity verification process.

Possible values: success, active, failed, waiting_for_prerequisite, not_applicable, skipped, expired, canceled, pending_review, manually_approved, manually_rejected
kyc_check
string
The status of a step in the identity verification process.

Possible values: success, active, failed, waiting_for_prerequisite, not_applicable, skipped, expired, canceled, pending_review, manually_approved, manually_rejected
documentary_verification
string
The status of a step in the identity verification process.

Possible values: success, active, failed, waiting_for_prerequisite, not_applicable, skipped, expired, canceled, pending_review, manually_approved, manually_rejected
selfie_check
string
The status of a step in the identity verification process.

Possible values: success, active, failed, waiting_for_prerequisite, not_applicable, skipped, expired, canceled, pending_review, manually_approved, manually_rejected
watchlist_screening
string
The status of a step in the identity verification process.

Possible values: success, active, failed, waiting_for_prerequisite, not_applicable, skipped, expired, canceled, pending_review, manually_approved, manually_rejected
risk_check
string
The status of a step in the identity verification process.

Possible values: success, active, failed, waiting_for_prerequisite, not_applicable, skipped, expired, canceled, pending_review, manually_approved, manually_rejected
documentary_verification
nullableobject
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.
status
string
The outcome status for the associated Identity Verification attempt's documentary_verification step. This field will always have the same value as steps.documentary_verification.
documents
[object]
An array of documents submitted to the documentary_verification step. Each entry represents one user submission, where each submission will contain both a front and back image, or just a front image, depending on the document type.
Note: Plaid will automatically let a user submit a new set of document images up to three times if we detect that a previous attempt might have failed due to user error. For example, if the first set of document images are blurry or obscured by glare, the user will be asked to capture their documents again, resulting in at least two separate entries within documents. If the overall documentary_verification is failed, the user has exhausted their retry attempts.
status
string
An outcome status for this specific document submission. Distinct from the overall documentary_verification.status that summarizes the verification outcome from one or more documents.

Possible values: success, failed, manually_approved
attempt
number
The attempt field begins with 1 and increments with each subsequent document upload.
images
object
URLs for downloading original and cropped images for this document submission. The URLs are designed to only allow downloading, not hot linking, so the URL will only serve the document image for 60 seconds before expiring. The expiration time is 60 seconds after the GET request for the associated Identity Verification attempt. A new expiring URL is generated with each request, so you can always rerequest the Identity Verification attempt if one of your URLs expires.
original_front
string
Temporary URL that expires after 60 seconds for downloading the uncropped original image of the front of the document.
original_back
nullablestring
Temporary URL that expires after 60 seconds for downloading the original image of the back of the document. Might be null if the back of the document was not collected.
cropped_front
nullablestring
Temporary URL that expires after 60 seconds for downloading a cropped image containing just the front of the document.
cropped_back
nullablestring
Temporary URL that expires after 60 seconds for downloading a cropped image containing just the back of the document. Might be null if the back of the document was not collected.
face
nullablestring
Temporary URL that expires after 60 seconds for downloading a crop of just the user's face from the document image. Might be null if the document does not contain a face photo.
extracted_data
nullableobject
Data extracted from a user-submitted document.
id_number
nullablestring
Alpha-numeric ID number extracted via OCR from the user's document image.
category
string
The type of identity document detected in the images provided. Will always be one of the following values:
drivers_license - A driver's license for the associated country
id_card - A general national identification card, distinct from driver's licenses
passport - A passport for the associated country
residence_permit_card - An identity document permitting a foreign citizen to temporarily reside in the associated country
resident_card - An identity document permitting a foreign citizen to permanently reside in the associated country
Note: This value may be different from the ID type that the user selects within Link. For example, if they select "Driver's License" but then submit a picture of a passport, this field will say passport

Possible values: drivers_license, id_card, passport, residence_permit_card, resident_card
expiration_date
nullablestring
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

Format: date
issuing_country
string
Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

Min length: 2
issuing_region
nullablestring
An ISO 3166-2 subdivision code. Related terms would be "state", "province", "prefecture", "zone", "subdivision", etc.
analysis
object
High level descriptions of how the associated document was processed. If a document fails verification, the details in the analysis object should help clarify why the document was rejected.
authenticity
string
High level summary of whether the document in the provided image matches the formatting rules and security checks for the associated jurisdiction.
For example, most identity documents have formatting rules like the following:
The image of the person's face must have a certain contrast in order to highlight skin tone
The subject in the document's image must remove eye glasses and pose in a certain way
The informational fields (name, date of birth, ID number, etc.) must be colored and aligned according to specific rules
Security features like watermarks and background patterns must be present
So a match status for this field indicates that the document in the provided image seems to conform to the various formatting and security rules associated with the detected document.

Possible values: match, partial_match, no_match, no_data
image_quality
string
A high level description of the quality of the image the user submitted.
For example, an image that is blurry, distorted by glare from a nearby light source, or improperly framed might be marked as low or medium quality. Poor quality images are more likely to fail OCR and/or template conformity checks.
Note: By default, Plaid will let a user recapture document images twice before failing the entire session if we attribute the failure to low image quality.

Possible values: high, medium, low
extracted_data
nullableobject
Analysis of the data extracted from the submitted document.
name
string
A match summary describing the cross comparison between the subject's name, extracted from the document image, and the name they separately provided to identity verification attempt.

Possible values: match, partial_match, no_match
date_of_birth
string
A match summary describing the cross comparison between the subject's date of birth, extracted from the document image, and the date of birth they separately provided to the identity verification attempt.

Possible values: match, partial_match, no_match
expiration_date
string
A description of whether the associated document was expired when the verification was performed.
Note: In the case where an expiration date is not present on the document or failed to be extracted, this value will be no_data.

Possible values: not_expired, expired, no_data
issuing_country
string
A binary match indicator specifying whether the country that issued the provided document matches the country that the user separately provided to Plaid.
Note: You can configure whether a no_match on issuing_country fails the documentary_verification by editing your Plaid Template.

Possible values: match, no_match
kyc_check
nullableobject
Additional information for the kyc_check step. This field will be null unless steps.kyc_check has reached a terminal state of either success or failed.
status
string
The outcome status for the associated Identity Verification attempt's kyc_check step. This field will always have the same value as steps.kyc_check.
address
object
Result summary object specifying how the address field matched.
summary
string
An enum indicating the match type between data provided by user and data checked against an external data source.
match indicates that the provided input data was a strong match against external data.
partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
no_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data.
no_data indicates that Plaid was unable to find external data to compare against the provided input data.
no_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user.

Possible values: match, partial_match, no_match, no_data, no_input
po_box
string
Field describing whether the associated address is a post office box. Will be yes when a P.O. box is detected, no when Plaid confirmed the address is not a P.O. box, and no_data when Plaid was not able to determine if the address is a P.O. box.

Possible values: yes, no, no_data
type
string
Field describing whether the associated address is being used for commercial or residential purposes.
Note: This value will be no_data when Plaid does not have sufficient data to determine the address's use.

Possible values: residential, commercial, no_data
name
object
Result summary object specifying how the name field matched.
summary
string
An enum indicating the match type between data provided by user and data checked against an external data source.
match indicates that the provided input data was a strong match against external data.
partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
no_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data.
no_data indicates that Plaid was unable to find external data to compare against the provided input data.
no_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user.

Possible values: match, partial_match, no_match, no_data, no_input
date_of_birth
object
Result summary object specifying how the date_of_birth field matched.
summary
string
An enum indicating the match type between data provided by user and data checked against an external data source.
match indicates that the provided input data was a strong match against external data.
partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
no_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data.
no_data indicates that Plaid was unable to find external data to compare against the provided input data.
no_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user.

Possible values: match, partial_match, no_match, no_data, no_input
id_number
object
Result summary object specifying how the id_number field matched.
summary
string
An enum indicating the match type between data provided by user and data checked against an external data source.
match indicates that the provided input data was a strong match against external data.
partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
no_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data.
no_data indicates that Plaid was unable to find external data to compare against the provided input data.
no_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user.

Possible values: match, partial_match, no_match, no_data, no_input
phone_number
object
Result summary object specifying how the phone field matched.
summary
string
An enum indicating the match type between data provided by user and data checked against an external data source.
match indicates that the provided input data was a strong match against external data.
partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
no_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data.
no_data indicates that Plaid was unable to find external data to compare against the provided input data.
no_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user.

Possible values: match, partial_match, no_match, no_data, no_input
watchlist_screening_id
nullablestring
ID of the associated screening.
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "id": "idv_52xR9LKo77r1Np",
3  "client_user_id": "your-db-id-3b24110",
4  "created_at": "2020-07-24T03:26:02Z",
5  "completed_at": "2020-07-24T03:26:02Z",
6  "previous_attempt_id": "idv_42cF1MNo42r9Xj",
7  "shareable_url": "https://flow.plaid.com/verify/idv_4FrXJvfQU3zGUR?key=e004115db797f7cc3083bff3167cba30644ef630fb46f5b086cde6cc3b86a36f",
8  "template": {
9    "id": "idvtmp_4FrXJvfQU3zGUR",
10    "version": 2
11  },
12  "user": {
13    "phone_number": "+19876543212",
14    "date_of_birth": "1990-05-29",
15    "ip_address": "192.0.2.42",
16    "email_address": "user@example.com",
17    "name": {
18      "given_name": "Leslie",
19      "family_name": "Knope"
20    },
21    "address": {
22      "street": "123 Main St.",
23      "street2": "Unit 42",
24      "city": "Pawnee",
25      "region": "IN",
26      "postal_code": "46001",
27      "country": "US"
28    },
29    "id_number": {
30      "value": "123456789",
31      "type": "us_ssn"
32    }
33  },
34  "status": "success",
35  "steps": {
36    "accept_tos": "success",
37    "verify_sms": "success",
38    "kyc_check": "success",
39    "documentary_verification": "success",
40    "selfie_check": "success",
41    "watchlist_screening": "success",
42    "risk_check": "success"
43  },
44  "documentary_verification": {
45    "status": "success",
46    "documents": [
47      {
48        "status": "success",
49        "attempt": 1,
50        "images": {
51          "original_front": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/original_front.jpeg",
52          "original_back": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/original_back.jpeg",
53          "cropped_front": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/cropped_front.jpeg",
54          "cropped_back": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/cropped_back.jpeg",
55          "face": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/face.jpeg"
56        },
57        "extracted_data": {
58          "id_number": "AB123456",
59          "category": "drivers_license",
60          "expiration_date": "1990-05-29",
61          "issuing_country": "US",
62          "issuing_region": "IN"
63        },
64        "analysis": {
65          "authenticity": "match",
66          "image_quality": "high",
67          "extracted_data": {
68            "name": "match",
69            "date_of_birth": "match",
70            "expiration_date": "not_expired",
71            "issuing_country": "match"
72          }
73        }
74      }
75    ]
76  },
77  "kyc_check": {
78    "status": "success",
79    "address": {
80      "summary": "match",
81      "po_box": "yes",
82      "type": "residential"
83    },
84    "name": {
85      "summary": "match"
86    },
87    "date_of_birth": {
88      "summary": "match"
89    },
90    "id_number": {
91      "summary": "match"
92    },
93    "phone_number": {
94      "summary": "match"
95    }
96  },
97  "watchlist_screening_id": "scr_52xR9LKo77r1Np",
98  "request_id": "saKrIBuEB9qJZng"
99}

Webhooks

STATUS_UPDATED

Fired when the status of an identity verification has been updated, which can be triggered via the dashboard or the API.

webhook_type
string
IDENTITY_VERIFICATION
webhook_code
string
STATUS_UPDATED
identity_verification_id
string
The ID of the associated Identity Verification attempt.
environment
string
The Plaid environment the webhook was sent from

Possible values: development, sandbox, production
1{
2  "webhook_type": "IDENTITY_VERIFICATION",
3  "webhook_code": "STATUS_UPDATED",
4  "identity_verification_id": "idv_52xR9LKo77r1Np",
5  "environment": "production"
6}

STEP_UPDATED

Fired when an end user has completed a step of the Identity Verification process.

webhook_type
string
IDENTITY_VERIFCATION
webhook_code
string
STEP_UPDATED
identity_verification_id
string
The ID of the associated Identity Verification attempt.
environment
string
The Plaid environment the webhook was sent from

Possible values: development, sandbox, production
1{
2  "webhook_type": "IDENTITY_VERIFICATION",
3  "webhook_code": "STEP_UPDATED",
4  "identity_verification_id": "idv_52xR9LKo77r1Np",
5  "environment": "production"
6}

RETRIED

Fired when identity verification has been retried, which can be triggered via the dashboard or the API.

webhook_type
string
IDENTITY_VERIFICATION
webhook_code
string
RETRIED
identity_verification_id
string
The ID of the associated Identity Verification attempt.
environment
string
The Plaid environment the webhook was sent from

Possible values: development, sandbox, production
1{
2  "webhook_type": "IDENTITY_VERIFICATION",
3  "webhook_code": "RETRIED",
4  "identity_verification_id": "idv_52xR9LKo77r1Np",
5  "environment": "production"
6}