Identity Verification
API reference for Identity Verification endpoints and webhooks
Endpoints | |
---|---|
/identity_verification/create | Create a new identity verification |
/identity_verification/get | Retrieve a previously created identity verification |
/identity_verification/list | Filter and list identity verifications |
/identity_verification/retry | Allow a user to retry an identity verification |
See also | |
---|---|
/dashboard_user/get | Retrieve information about a dashboard user |
/dashboard_user/list | List dashboard users |
Webhooks | |
---|---|
STATUS_UPDATED | The status of an identity verification has been updated |
STEP_UPDATED | A step in the identity verification process has been completed |
RETRIED | An 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.
You can also use this endpoint to supply information you already have collected about the user; if any of these fields are specified, the screens prompting the user to enter them will be skipped during the Link flow.
client_user_id
/link/token/create
client_user_id
to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the client_user_id
.is_shareable
template_id
gave_consent
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.false
user
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.
If you are not using the shareable URL feature, you can optionally provide these fields via /link/token/create
instead; both /identity_verification/create
and /link/token/create
are valid ways to provide this information. Note that if you provide a non-null
user data object via /identity_verification/create
, any user data fields entered via /link/token/create
for the same client_user_id
will be ignored when prefilling Link.email_address
email
phone_number
date_of_birth
date
name
given_name
family_name
address
For more context on this field, see Input Validation by Country.
street
street2
city
region
postal_code
country
id_number
null
. Otherwise, both fields are guaranteed to be filled.value
type
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_user_id
user.client_user_id
is deprecated. Please provide client_user_id
at the root level instead.client_id
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
secret
. The secret
is required and may be provided either in the PLAID-SECRET
header or as part of a request body.is_idempotent
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 client_user_id: 'user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d',3 is_shareable: true,4 template_id: 'idvtmp_52xR9LKo77r1Np',5 gave_consent: true,6 user: {7 email_address: 'acharleston@email.com',8 phone_number: '+12345678909',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 error32}
Response fields and example
id
client_user_id
/link/token/create
client_user_id
to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the client_user_id
.created_at
date-time
completed_at
date-time
previous_attempt_id
shareable_url
user
phone_number
date_of_birth
date
ip_address
email_address
email
name
given_name
family_name
address
Addresses from the United Kingdom will not include a region
Addresses from Hong Kong will not include postal code
street
street2
city
region
postal_code
country
id_number
null
. Otherwise, both fields are guaranteed to be filled.value
type
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
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 templatefailed
- The user failed one or more steps in the session and was told to contact support.expired
- The Identity Verification attempt was active for a long period of time without being completed and was automatically marked as expired. Note that sessions currently do not expire. Automatic expiration is expected to be enabled in the future.canceled
- The Identity Verification attempt was canceled, either via the dashboard by a user, or via API. The user may have completed part of the session, but has neither failed or passed.pending_review
- The Identity Verification attempt template was configured to perform a screening that had one or more hits needing review.active
, success
, failed
, expired
, canceled
, pending_review
steps
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
success
, active
, failed
, waiting_for_prerequisite
, not_applicable
, skipped
, expired
, canceled
, pending_review
, manually_approved
, manually_rejected
verify_sms
success
, active
, failed
, waiting_for_prerequisite
, not_applicable
, skipped
, expired
, canceled
, pending_review
, manually_approved
, manually_rejected
kyc_check
success
, active
, failed
, waiting_for_prerequisite
, not_applicable
, skipped
, expired
, canceled
, pending_review
, manually_approved
, manually_rejected
documentary _verification
success
, active
, failed
, waiting_for_prerequisite
, not_applicable
, skipped
, expired
, canceled
, pending_review
, manually_approved
, manually_rejected
selfie_check
success
, active
, failed
, waiting_for_prerequisite
, not_applicable
, skipped
, expired
, canceled
, pending_review
, manually_approved
, manually_rejected
watchlist_screening
success
, active
, failed
, waiting_for_prerequisite
, not_applicable
, skipped
, expired
, canceled
, pending_review
, manually_approved
, manually_rejected
risk_check
success
, active
, failed
, waiting_for_prerequisite
, not_applicable
, skipped
, expired
, canceled
, pending_review
, manually_approved
, manually_rejected
documentary _verification
documentary_verification
step. This field will be null
unless steps.documentary_verification
has reached a terminal state of either success
or failed
.status
documentary_verification
step. This field will always have the same value as steps.documentary_verification
.documents
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
documentary_verification.status
that summarizes the verification outcome from one or more documents.success
, failed
, manually_approved
attempt
attempt
field begins with 1 and increments with each subsequent document upload.images
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
original_back
cropped_front
cropped_back
face
extracted_data
id_number
category
drivers_license
- A driver's license issued by the associated country, establishing identity without any guarantee as to citizenship, and granting driving privilegesid_card
- A general national identification card, distinct from driver's licenses as it only establishes identitypassport
- A travel passport issued by the associated country for one of its citizensresidence_permit_card
- An identity document issued by the associated country permitting a foreign citizen to temporarily reside thereresident_card
- An identity document issued by the associated country permitting a foreign citizen to permanently reside therevisa
- An identity document issued by the associated country permitting a foreign citizen entry for a short duration and for a specific purpose, typically no longer than 6 monthsNote: 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
drivers_license
, id_card
, passport
, residence_permit_card
, resident_card
, visa
expiration_date
date
issuing_country
issuing_region
date_of_birth
date
address
street
, city
, country
. If any are missing or unable to be extracted, the address will be null.region
, and postal_code
may be null based on the addressing system. For example:Addresses from the United Kingdom will not include a region
Addresses from Hong Kong will not include postal code
Note: Optical Character Recognition (OCR) technology may sometimes extract incorrect data from a document.
street
city
region
postal_code
country
name
given_name
family_name
analysis
analysis
object should help clarify why the document was rejected.authenticity
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.match
, partial_match
, no_match
, no_data
image_quality
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.
high
, medium
, low
extracted_data
name
match
, partial_match
, no_match
, no_data
date_of_birth
match
, partial_match
, no_match
, no_data
expiration_date
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
.not_expired
, expired
, no_data
issuing_country
Note: You can configure whether a
no_match
on issuing_country
fails the documentary_verification
by editing your Plaid Template.match
, no_match
redacted_at
date-time
selfie_check
selfie_check
step. This field will be null
unless steps.selfie_check
has reached a terminal state of either success
or failed
.status
selfie_check
step. This field will always have the same value as steps.selfie_check
.success
, failed
selfies
selfie_check
step. Each entry represents one user submission.status
selfie_check.status
that summarizes the verification outcome from one or more selfies.success
, failed
attempt
attempt
field begins with 1 and increments with each subsequent selfie upload.analysis
analysis
object should help clarify why the selfie was rejected.document_comparison
match
, no_match
, no_input
liveness_check
success
, failed
kyc_check
kyc_check
(Data Source Verification) step. This field will be null
unless steps.kyc_check
has reached a terminal state of either success
or failed
.status
kyc_check
step. This field will always have the same value as steps.kyc_check
.address
address
field matched.summary
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.match
, partial_match
, no_match
, no_data
, no_input
po_box
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.yes
, no
, no_data
type
Note: This value will be
no_data
when Plaid does not have sufficient data to determine the address's use.residential
, commercial
, no_data
name
name
field matched.summary
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.match
, partial_match
, no_match
, no_data
, no_input
date_of_birth
date_of_birth
field matched.summary
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.match
, partial_match
, no_match
, no_data
, no_input
id_number
id_number
field matched.summary
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.match
, partial_match
, no_match
, no_data
, no_input
phone_number
phone
field matched.summary
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.match
, partial_match
, no_match
, no_data
, no_input
area_code
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.match
, partial_match
, no_match
, no_data
, no_input
risk_check
risk_check
step.status
success
, active
, failed
, waiting_for_prerequisite
, not_applicable
, skipped
, expired
, canceled
, pending_review
, manually_approved
, manually_rejected
behavior
behavior
attributes of risk check, when available.user_interactions
genuine
indicates the user has high familiarity with the data they are providing, and that fraud is unlikely.neutral
indicates some signals are present in between risky
and genuine
, but there are not enough clear signals to determine an outcome.risky
indicates the user has low familiarity with the data they are providing, and that fraud is likely.no_data
indicates there is not sufficient information to give an accurate signal.genuine
, neutral
, risky
, no_data
fraud_ring_detected
yes
indicates that fraud ring activity was detected.no
indicates that fraud ring activity was not detected.no_data
indicates there was not enough information available to give an accurate signal.yes
, no
, no_data
bot_detected
yes
indicates that automated activity was detected.no
indicates that automated activity was not detected.no_data
indicates there was not enough information available to give an accurate signal.yes
, no
, no_data
email
email
attributes of risk check.is_deliverable
yes
, no
, no_data
breach_count
first_breached_at
date
last_breached_at
date
domain_registered_at
date
domain_is_free _provider
yes
, no
, no_data
domain_is_custom
yes
, no
, no_data
domain_is_disposable
yes
, no
, no_data
top_level_domain_is _suspicious
yes
, no
, no_data
linked_services
aboutme
, adobe
, adult_sites
, airbnb
, altbalaji
, amazon
, apple
, archiveorg
, atlassian
, bitmoji
, bodybuilding
, booking
, bukalapak
, codecademy
, deliveroo
, diigo
, discord
, disneyplus
, duolingo
, ebay
, envato
, eventbrite
, evernote
, facebook
, firefox
, flickr
, flipkart
, foursquare
, freelancer
, gaana
, giphy
, github
, google
, gravatar
, hubspot
, imgur
, instagram
, jdid
, kakao
, kommo
, komoot
, lastfm
, lazada
, line
, linkedin
, mailru
, microsoft
, myspace
, netflix
, nike
, ok
, patreon
, pinterest
, plurk
, quora
, qzone
, rambler
, rappi
, replit
, samsung
, seoclerks
, shopclues
, skype
, snapchat
, snapdeal
, soundcloud
, spotify
, starz
, strava
, taringa
, telegram
, tiki
, tokopedia
, treehouse
, tumblr
, twitter
, venmo
, viber
, vimeo
, vivino
, vkontakte
, wattpad
, weibo
, whatsapp
, wordpress
, xing
, yahoo
, yandex
, zalo
, zoho
phone
phone
attributes of risk check.linked_services
aboutme
, adobe
, adult_sites
, airbnb
, altbalaji
, amazon
, apple
, archiveorg
, atlassian
, bitmoji
, bodybuilding
, booking
, bukalapak
, codecademy
, deliveroo
, diigo
, discord
, disneyplus
, duolingo
, ebay
, envato
, eventbrite
, evernote
, facebook
, firefox
, flickr
, flipkart
, foursquare
, freelancer
, gaana
, giphy
, github
, google
, gravatar
, hubspot
, imgur
, instagram
, jdid
, kakao
, kommo
, komoot
, lastfm
, lazada
, line
, linkedin
, mailru
, microsoft
, myspace
, netflix
, nike
, ok
, patreon
, pinterest
, plurk
, quora
, qzone
, rambler
, rappi
, replit
, samsung
, seoclerks
, shopclues
, skype
, snapchat
, snapdeal
, soundcloud
, spotify
, starz
, strava
, taringa
, telegram
, tiki
, tokopedia
, treehouse
, tumblr
, twitter
, venmo
, viber
, vimeo
, vivino
, vkontakte
, wattpad
, weibo
, whatsapp
, wordpress
, xing
, yahoo
, yandex
, zalo
, zoho
devices
device
attributes of risk check.ip_proxy_type
none_detected
indicates the user is not on a detectable proxy network.tor
indicates the user was using a Tor browser, which sends encrypted traffic on a decentralized network and is somewhat similar to a VPN (Virtual Private Network).vpn
indicates the user is on a VPN (Virtual Private Network)web_proxy
indicates the user is on a web proxy server, which may allow them to conceal information such as their IP address or other identifying information.public_proxy
indicates the user is on a public web proxy server, which is similar to a web proxy but can be shared by multiple users. This may allow multiple users to appear as if they have the same IP address for instance.none_detected
, tor
, vpn
, web_proxy
, public_proxy
ip_spam_list_count
ip_timezone_offset
identity_abuse_signals
identity abuse
, e.g. stolen and synthetic identity fraud. These attributes are only available for US identities and some signals may not be available depending on what information was collected.synthetic_identity
Contains the following fields:
score
- A score from 0 to 100 indicating the likelihood that the user is a synthetic identity.score
stolen_identity
Contains the following fields:
score
- A score from 0 to 100 indicating the likelihood that the user is a stolen identity.score
verify_sms
verify_sms
step.status
verify_sms
step. This field will always have the same value as steps.verify_sms
.success
, failed
verifications
verify_sms
step. Each entry represents one user-submitted phone number. Phone number edits, and in some cases error handling due to edge cases like rate limiting, may generate additional verifications.status
pending
, success
, failed
, canceled
attempt
phone_number
delivery_attempt_count
solve_attempt_count
initially_sent_at
date-time
last_sent_at
date-time
redacted_at
date-time
watchlist_screening_id
beacon_user_id
redacted_at
date-time
request_id
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": 211 },12 "user": {13 "phone_number": "+12345678909",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 "date_of_birth": "1990-05-29",64 "address": {65 "street": "123 Main St. Unit 42",66 "city": "Pawnee",67 "region": "IN",68 "postal_code": "46001",69 "country": "US"70 },71 "name": {72 "given_name": "Leslie",73 "family_name": "Knope"74 }75 },76 "analysis": {77 "authenticity": "match",78 "image_quality": "high",79 "extracted_data": {80 "name": "match",81 "date_of_birth": "match",82 "expiration_date": "not_expired",83 "issuing_country": "match"84 }85 },86 "redacted_at": "2020-07-24T03:26:02Z"87 }88 ]89 },90 "selfie_check": {91 "status": "success",92 "selfies": [93 {94 "status": "success",95 "attempt": 1,96 "capture": {97 "image_url": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/selfie/liveness.jpeg",98 "video_url": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/selfie/liveness.webm"99 },100 "analysis": {101 "document_comparison": "match",102 "liveness_check": "success"103 }104 }105 ]106 },107 "kyc_check": {108 "status": "success",109 "address": {110 "summary": "match",111 "po_box": "yes",112 "type": "residential"113 },114 "name": {115 "summary": "match"116 },117 "date_of_birth": {118 "summary": "match"119 },120 "id_number": {121 "summary": "match"122 },123 "phone_number": {124 "summary": "match",125 "area_code": "match"126 }127 },128 "risk_check": {129 "status": "success",130 "behavior": {131 "user_interactions": "risky",132 "fraud_ring_detected": "yes",133 "bot_detected": "yes"134 },135 "email": {136 "is_deliverable": "yes",137 "breach_count": 1,138 "first_breached_at": "1990-05-29",139 "last_breached_at": "1990-05-29",140 "domain_registered_at": "1990-05-29",141 "domain_is_free_provider": "yes",142 "domain_is_custom": "yes",143 "domain_is_disposable": "yes",144 "top_level_domain_is_suspicious": "yes",145 "linked_services": [146 "apple"147 ]148 },149 "phone": {150 "linked_services": [151 "apple"152 ]153 },154 "devices": [155 {156 "ip_proxy_type": "none_detected",157 "ip_spam_list_count": 1,158 "ip_timezone_offset": "+06:00:00"159 }160 ],161 "identity_abuse_signals": {162 "synthetic_identity": {163 "score": 0164 },165 "stolen_identity": {166 "score": 0167 }168 }169 },170 "verify_sms": {171 "status": "success",172 "verifications": [173 {174 "status": "success",175 "attempt": 1,176 "phone_number": "+12345678909",177 "delivery_attempt_count": 1,178 "solve_attempt_count": 1,179 "initially_sent_at": "2020-07-24T03:26:02Z",180 "last_sent_at": "2020-07-24T03:26:02Z",181 "redacted_at": "2020-07-24T03:26:02Z"182 }183 ]184 },185 "watchlist_screening_id": "scr_52xR9LKo77r1Np",186 "beacon_user_id": "becusr_42cF1MNo42r9Xj",187 "redacted_at": "2020-07-24T03:26:02Z",188 "request_id": "saKrIBuEB9qJZng"189}
Was this helpful?
/identity_verification/get
Retrieve Identity Verification
Retrieve a previously created Identity Verification.
identity_verification/getidentity_verification _id
secret
secret
. The secret
is required and may be provided either in the PLAID-SECRET
header or as part of a request body.client_id
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 error8}
Response fields and example
id
client_user_id
/link/token/create
client_user_id
to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the client_user_id
.created_at
date-time
completed_at
date-time
previous_attempt_id
shareable_url
user
phone_number
date_of_birth
date
ip_address
email_address
email
name
given_name
family_name
address
Addresses from the United Kingdom will not include a region
Addresses from Hong Kong will not include postal code
street
street2
city
region
postal_code
country
id_number
null
. Otherwise, both fields are guaranteed to be filled.value
type
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
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 templatefailed
- The user failed one or more steps in the session and was told to contact support.expired
- The Identity Verification attempt was active for a long period of time without being completed and was automatically marked as expired. Note that sessions currently do not expire. Automatic expiration is expected to be enabled in the future.canceled
- The Identity Verification attempt was canceled, either via the dashboard by a user, or via API. The user may have completed part of the session, but has neither failed or passed.pending_review
- The Identity Verification attempt template was configured to perform a screening that had one or more hits needing review.active
, success
, failed
, expired
, canceled
, pending_review
steps
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
success
, active
, failed
, waiting_for_prerequisite
, not_applicable
, skipped
, expired
, canceled
, pending_review
, manually_approved
, manually_rejected
verify_sms
success
, active
, failed
, waiting_for_prerequisite
, not_applicable
, skipped
, expired
, canceled
, pending_review
, manually_approved
, manually_rejected
kyc_check
success
, active
, failed
, waiting_for_prerequisite
, not_applicable
, skipped
, expired
, canceled
, pending_review
, manually_approved
, manually_rejected
documentary _verification
success
, active
, failed
, waiting_for_prerequisite
, not_applicable
, skipped
, expired
, canceled
, pending_review
, manually_approved
, manually_rejected
selfie_check
success
, active
, failed
, waiting_for_prerequisite
, not_applicable
, skipped
, expired
, canceled
, pending_review
, manually_approved
, manually_rejected
watchlist_screening
success
, active
, failed
, waiting_for_prerequisite
, not_applicable
, skipped
, expired
, canceled
, pending_review
, manually_approved
, manually_rejected
risk_check
success
, active
, failed
, waiting_for_prerequisite
, not_applicable
, skipped
, expired
, canceled
, pending_review
, manually_approved
, manually_rejected
documentary _verification
documentary_verification
step. This field will be null
unless steps.documentary_verification
has reached a terminal state of either success
or failed
.status
documentary_verification
step. This field will always have the same value as steps.documentary_verification
.documents
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
documentary_verification.status
that summarizes the verification outcome from one or more documents.success
, failed
, manually_approved
attempt
attempt
field begins with 1 and increments with each subsequent document upload.images
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
original_back
cropped_front
cropped_back
face
extracted_data
id_number
category
drivers_license
- A driver's license issued by the associated country, establishing identity without any guarantee as to citizenship, and granting driving privilegesid_card
- A general national identification card, distinct from driver's licenses as it only establishes identitypassport
- A travel passport issued by the associated country for one of its citizensresidence_permit_card
- An identity document issued by the associated country permitting a foreign citizen to temporarily reside thereresident_card
- An identity document issued by the associated country permitting a foreign citizen to permanently reside therevisa
- An identity document issued by the associated country permitting a foreign citizen entry for a short duration and for a specific purpose, typically no longer than 6 monthsNote: 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
drivers_license
, id_card
, passport
, residence_permit_card
, resident_card
, visa
expiration_date
date
issuing_country
issuing_region
date_of_birth
date
address
street
, city
, country
. If any are missing or unable to be extracted, the address will be null.region
, and postal_code
may be null based on the addressing system. For example:Addresses from the United Kingdom will not include a region
Addresses from Hong Kong will not include postal code
Note: Optical Character Recognition (OCR) technology may sometimes extract incorrect data from a document.
street
city
region
postal_code
country
name
given_name
family_name
analysis
analysis
object should help clarify why the document was rejected.authenticity
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.match
, partial_match
, no_match
, no_data
image_quality
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.
high
, medium
, low
extracted_data
name
match
, partial_match
, no_match
, no_data
date_of_birth
match
, partial_match
, no_match
, no_data
expiration_date
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
.not_expired
, expired
, no_data
issuing_country
Note: You can configure whether a
no_match
on issuing_country
fails the documentary_verification
by editing your Plaid Template.match
, no_match
redacted_at
date-time
selfie_check
selfie_check
step. This field will be null
unless steps.selfie_check
has reached a terminal state of either success
or failed
.status
selfie_check
step. This field will always have the same value as steps.selfie_check
.success
, failed
selfies
selfie_check
step. Each entry represents one user submission.status
selfie_check.status
that summarizes the verification outcome from one or more selfies.success
, failed
attempt
attempt
field begins with 1 and increments with each subsequent selfie upload.analysis
analysis
object should help clarify why the selfie was rejected.document_comparison
match
, no_match
, no_input
liveness_check
success
, failed
kyc_check
kyc_check
(Data Source Verification) step. This field will be null
unless steps.kyc_check
has reached a terminal state of either success
or failed
.status
kyc_check
step. This field will always have the same value as steps.kyc_check
.address
address
field matched.summary
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.match
, partial_match
, no_match
, no_data
, no_input
po_box
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.yes
, no
, no_data
type
Note: This value will be
no_data
when Plaid does not have sufficient data to determine the address's use.residential
, commercial
, no_data
name
name
field matched.summary
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.match
, partial_match
, no_match
, no_data
, no_input
date_of_birth
date_of_birth
field matched.summary
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.match
, partial_match
, no_match
, no_data
, no_input
id_number
id_number
field matched.summary
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.match
, partial_match
, no_match
, no_data
, no_input
phone_number
phone
field matched.summary
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.match
, partial_match
, no_match
, no_data
, no_input
area_code
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.match
, partial_match
, no_match
, no_data
, no_input
risk_check
risk_check
step.status
success
, active
, failed
, waiting_for_prerequisite
, not_applicable
, skipped
, expired
, canceled
, pending_review
, manually_approved
, manually_rejected
behavior
behavior
attributes of risk check, when available.user_interactions
genuine
indicates the user has high familiarity with the data they are providing, and that fraud is unlikely.neutral
indicates some signals are present in between risky
and genuine
, but there are not enough clear signals to determine an outcome.risky
indicates the user has low familiarity with the data they are providing, and that fraud is likely.no_data
indicates there is not sufficient information to give an accurate signal.genuine
, neutral
, risky
, no_data
fraud_ring_detected
yes
indicates that fraud ring activity was detected.no
indicates that fraud ring activity was not detected.no_data
indicates there was not enough information available to give an accurate signal.yes
, no
, no_data
bot_detected
yes
indicates that automated activity was detected.no
indicates that automated activity was not detected.no_data
indicates there was not enough information available to give an accurate signal.yes
, no
, no_data
email
email
attributes of risk check.is_deliverable
yes
, no
, no_data
breach_count
first_breached_at
date
last_breached_at
date
domain_registered_at
date
domain_is_free _provider
yes
, no
, no_data
domain_is_custom
yes
, no
, no_data
domain_is_disposable
yes
, no
, no_data
top_level_domain_is _suspicious
yes
, no
, no_data
linked_services
aboutme
, adobe
, adult_sites
, airbnb
, altbalaji
, amazon
, apple
, archiveorg
, atlassian
, bitmoji
, bodybuilding
, booking
, bukalapak
, codecademy
, deliveroo
, diigo
, discord
, disneyplus
, duolingo
, ebay
, envato
, eventbrite
, evernote
, facebook
, firefox
, flickr
, flipkart
, foursquare
, freelancer
, gaana
, giphy
, github
, google
, gravatar
, hubspot
, imgur
, instagram
, jdid
, kakao
, kommo
, komoot
, lastfm
, lazada
, line
, linkedin
, mailru
, microsoft
, myspace
, netflix
, nike
, ok
, patreon
, pinterest
, plurk
, quora
, qzone
, rambler
, rappi
, replit
, samsung
, seoclerks
, shopclues
, skype
, snapchat
, snapdeal
, soundcloud
, spotify
, starz
, strava
, taringa
, telegram
, tiki
, tokopedia
, treehouse
, tumblr
, twitter
, venmo
, viber
, vimeo
, vivino
, vkontakte
, wattpad
, weibo
, whatsapp
, wordpress
, xing
, yahoo
, yandex
, zalo
, zoho
phone
phone
attributes of risk check.linked_services
aboutme
, adobe
, adult_sites
, airbnb
, altbalaji
, amazon
, apple
, archiveorg
, atlassian
, bitmoji
, bodybuilding
, booking
, bukalapak
, codecademy
, deliveroo
, diigo
, discord
, disneyplus
, duolingo
, ebay
, envato
, eventbrite
, evernote
, facebook
, firefox
, flickr
, flipkart
, foursquare
, freelancer
, gaana
, giphy
, github
, google
, gravatar
, hubspot
, imgur
, instagram
, jdid
, kakao
, kommo
, komoot
, lastfm
, lazada
, line
, linkedin
, mailru
, microsoft
, myspace
, netflix
, nike
, ok
, patreon
, pinterest
, plurk
, quora
, qzone
, rambler
, rappi
, replit
, samsung
, seoclerks
, shopclues
, skype
, snapchat
, snapdeal
, soundcloud
, spotify
, starz
, strava
, taringa
, telegram
, tiki
, tokopedia
, treehouse
, tumblr
, twitter
, venmo
, viber
, vimeo
, vivino
, vkontakte
, wattpad
, weibo
, whatsapp
, wordpress
, xing
, yahoo
, yandex
, zalo
, zoho
devices
device
attributes of risk check.ip_proxy_type
none_detected
indicates the user is not on a detectable proxy network.tor
indicates the user was using a Tor browser, which sends encrypted traffic on a decentralized network and is somewhat similar to a VPN (Virtual Private Network).vpn
indicates the user is on a VPN (Virtual Private Network)web_proxy
indicates the user is on a web proxy server, which may allow them to conceal information such as their IP address or other identifying information.public_proxy
indicates the user is on a public web proxy server, which is similar to a web proxy but can be shared by multiple users. This may allow multiple users to appear as if they have the same IP address for instance.none_detected
, tor
, vpn
, web_proxy
, public_proxy
ip_spam_list_count
ip_timezone_offset
identity_abuse_signals
identity abuse
, e.g. stolen and synthetic identity fraud. These attributes are only available for US identities and some signals may not be available depending on what information was collected.synthetic_identity
Contains the following fields:
score
- A score from 0 to 100 indicating the likelihood that the user is a synthetic identity.score
stolen_identity
Contains the following fields:
score
- A score from 0 to 100 indicating the likelihood that the user is a stolen identity.score
verify_sms
verify_sms
step.status
verify_sms
step. This field will always have the same value as steps.verify_sms
.success
, failed
verifications
verify_sms
step. Each entry represents one user-submitted phone number. Phone number edits, and in some cases error handling due to edge cases like rate limiting, may generate additional verifications.status
pending
, success
, failed
, canceled
attempt
phone_number
delivery_attempt_count
solve_attempt_count
initially_sent_at
date-time
last_sent_at
date-time
redacted_at
date-time
watchlist_screening_id
beacon_user_id
redacted_at
date-time
request_id
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": 211 },12 "user": {13 "phone_number": "+12345678909",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 "date_of_birth": "1990-05-29",64 "address": {65 "street": "123 Main St. Unit 42",66 "city": "Pawnee",67 "region": "IN",68 "postal_code": "46001",69 "country": "US"70 },71 "name": {72 "given_name": "Leslie",73 "family_name": "Knope"74 }75 },76 "analysis": {77 "authenticity": "match",78 "image_quality": "high",79 "extracted_data": {80 "name": "match",81 "date_of_birth": "match",82 "expiration_date": "not_expired",83 "issuing_country": "match"84 }85 },86 "redacted_at": "2020-07-24T03:26:02Z"87 }88 ]89 },90 "selfie_check": {91 "status": "success",92 "selfies": [93 {94 "status": "success",95 "attempt": 1,96 "capture": {97 "image_url": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/selfie/liveness.jpeg",98 "video_url": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/selfie/liveness.webm"99 },100 "analysis": {101 "document_comparison": "match",102 "liveness_check": "success"103 }104 }105 ]106 },107 "kyc_check": {108 "status": "success",109 "address": {110 "summary": "match",111 "po_box": "yes",112 "type": "residential"113 },114 "name": {115 "summary": "match"116 },117 "date_of_birth": {118 "summary": "match"119 },120 "id_number": {121 "summary": "match"122 },123 "phone_number": {124 "summary": "match",125 "area_code": "match"126 }127 },128 "risk_check": {129 "status": "success",130 "behavior": {131 "user_interactions": "risky",132 "fraud_ring_detected": "yes",133 "bot_detected": "yes"134 },135 "email": {136 "is_deliverable": "yes",137 "breach_count": 1,138 "first_breached_at": "1990-05-29",139 "last_breached_at": "1990-05-29",140 "domain_registered_at": "1990-05-29",141 "domain_is_free_provider": "yes",142 "domain_is_custom": "yes",143 "domain_is_disposable": "yes",144 "top_level_domain_is_suspicious": "yes",145 "linked_services": [146 "apple"147 ]148 },149 "phone": {150 "linked_services": [151 "apple"152 ]153 },154 "devices": [155 {156 "ip_proxy_type": "none_detected",157 "ip_spam_list_count": 1,158 "ip_timezone_offset": "+06:00:00"159 }160 ],161 "identity_abuse_signals": {162 "synthetic_identity": {163 "score": 0164 },165 "stolen_identity": {166 "score": 0167 }168 }169 },170 "verify_sms": {171 "status": "success",172 "verifications": [173 {174 "status": "success",175 "attempt": 1,176 "phone_number": "+12345678909",177 "delivery_attempt_count": 1,178 "solve_attempt_count": 1,179 "initially_sent_at": "2020-07-24T03:26:02Z",180 "last_sent_at": "2020-07-24T03:26:02Z",181 "redacted_at": "2020-07-24T03:26:02Z"182 }183 ]184 },185 "watchlist_screening_id": "scr_52xR9LKo77r1Np",186 "beacon_user_id": "becusr_42cF1MNo42r9Xj",187 "redacted_at": "2020-07-24T03:26:02Z",188 "request_id": "saKrIBuEB9qJZng"189}
Was this helpful?
/identity_verification/list
List Identity Verifications
Filter and list Identity Verifications created by your account
identity_verification/listsecret
secret
. The secret
is required and may be provided either in the PLAID-SECRET
header or as part of a request body.client_id
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
client_user_id
/link/token/create
client_user_id
to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the client_user_id
.cursor
1const request: ListIdentityVerificationRequest = {2 template_id: 'idvtmp_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 error9}
Response fields and example
identity_verifications
id
client_user_id
/link/token/create
client_user_id
to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the client_user_id
.created_at
date-time
completed_at
date-time
previous_attempt_id
shareable_url
user
phone_number
date_of_birth
date
ip_address
email_address
email
name
given_name
family_name
address
Addresses from the United Kingdom will not include a region
Addresses from Hong Kong will not include postal code
street
street2
city
region
postal_code
country
id_number
null
. Otherwise, both fields are guaranteed to be filled.value
type
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
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 templatefailed
- The user failed one or more steps in the session and was told to contact support.expired
- The Identity Verification attempt was active for a long period of time without being completed and was automatically marked as expired. Note that sessions currently do not expire. Automatic expiration is expected to be enabled in the future.canceled
- The Identity Verification attempt was canceled, either via the dashboard by a user, or via API. The user may have completed part of the session, but has neither failed or passed.pending_review
- The Identity Verification attempt template was configured to perform a screening that had one or more hits needing review.active
, success
, failed
, expired
, canceled
, pending_review
steps
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
success
, active
, failed
, waiting_for_prerequisite
, not_applicable
, skipped
, expired
, canceled
, pending_review
, manually_approved
, manually_rejected
verify_sms
success
, active
, failed
, waiting_for_prerequisite
, not_applicable
, skipped
, expired
, canceled
, pending_review
, manually_approved
, manually_rejected
kyc_check
success
, active
, failed
, waiting_for_prerequisite
, not_applicable
, skipped
, expired
, canceled
, pending_review
, manually_approved
, manually_rejected
documentary _verification
success
, active
, failed
, waiting_for_prerequisite
, not_applicable
, skipped
, expired
, canceled
, pending_review
, manually_approved
, manually_rejected
selfie_check
success
, active
, failed
, waiting_for_prerequisite
, not_applicable
, skipped
, expired
, canceled
, pending_review
, manually_approved
, manually_rejected
watchlist_screening
success
, active
, failed
, waiting_for_prerequisite
, not_applicable
, skipped
, expired
, canceled
, pending_review
, manually_approved
, manually_rejected
risk_check
success
, active
, failed
, waiting_for_prerequisite
, not_applicable
, skipped
, expired
, canceled
, pending_review
, manually_approved
, manually_rejected
documentary _verification
documentary_verification
step. This field will be null
unless steps.documentary_verification
has reached a terminal state of either success
or failed
.status
documentary_verification
step. This field will always have the same value as steps.documentary_verification
.documents
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
documentary_verification.status
that summarizes the verification outcome from one or more documents.success
, failed
, manually_approved
attempt
attempt
field begins with 1 and increments with each subsequent document upload.images
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
original_back
cropped_front
cropped_back
face
extracted_data
id_number
category
drivers_license
- A driver's license issued by the associated country, establishing identity without any guarantee as to citizenship, and granting driving privilegesid_card
- A general national identification card, distinct from driver's licenses as it only establishes identitypassport
- A travel passport issued by the associated country for one of its citizensresidence_permit_card
- An identity document issued by the associated country permitting a foreign citizen to temporarily reside thereresident_card
- An identity document issued by the associated country permitting a foreign citizen to permanently reside therevisa
- An identity document issued by the associated country permitting a foreign citizen entry for a short duration and for a specific purpose, typically no longer than 6 monthsNote: 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
drivers_license
, id_card
, passport
, residence_permit_card
, resident_card
, visa
expiration_date
date
issuing_country
issuing_region
date_of_birth
date
address
street
, city
, country
. If any are missing or unable to be extracted, the address will be null.region
, and postal_code
may be null based on the addressing system. For example:Addresses from the United Kingdom will not include a region
Addresses from Hong Kong will not include postal code
Note: Optical Character Recognition (OCR) technology may sometimes extract incorrect data from a document.
street
city
region
postal_code
country
name
given_name
family_name
analysis
analysis
object should help clarify why the document was rejected.authenticity
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.match
, partial_match
, no_match
, no_data
image_quality
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.
high
, medium
, low
extracted_data
name
match
, partial_match
, no_match
, no_data
date_of_birth
match
, partial_match
, no_match
, no_data
expiration_date
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
.not_expired
, expired
, no_data
issuing_country
Note: You can configure whether a
no_match
on issuing_country
fails the documentary_verification
by editing your Plaid Template.match
, no_match
redacted_at
date-time
selfie_check
selfie_check
step. This field will be null
unless steps.selfie_check
has reached a terminal state of either success
or failed
.status
selfie_check
step. This field will always have the same value as steps.selfie_check
.success
, failed
selfies
selfie_check
step. Each entry represents one user submission.status
selfie_check.status
that summarizes the verification outcome from one or more selfies.success
, failed
attempt
attempt
field begins with 1 and increments with each subsequent selfie upload.analysis
analysis
object should help clarify why the selfie was rejected.document_comparison
match
, no_match
, no_input
liveness_check
success
, failed
kyc_check
kyc_check
(Data Source Verification) step. This field will be null
unless steps.kyc_check
has reached a terminal state of either success
or failed
.status
kyc_check
step. This field will always have the same value as steps.kyc_check
.address
address
field matched.summary
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.match
, partial_match
, no_match
, no_data
, no_input
po_box
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.yes
, no
, no_data
type
Note: This value will be
no_data
when Plaid does not have sufficient data to determine the address's use.residential
, commercial
, no_data
name
name
field matched.summary
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.match
, partial_match
, no_match
, no_data
, no_input
date_of_birth
date_of_birth
field matched.summary
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.match
, partial_match
, no_match
, no_data
, no_input
id_number
id_number
field matched.summary
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.match
, partial_match
, no_match
, no_data
, no_input
phone_number
phone
field matched.summary
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.match
, partial_match
, no_match
, no_data
, no_input
area_code
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.match
, partial_match
, no_match
, no_data
, no_input
risk_check
risk_check
step.status
success
, active
, failed
, waiting_for_prerequisite
, not_applicable
, skipped
, expired
, canceled
, pending_review
, manually_approved
, manually_rejected
behavior
behavior
attributes of risk check, when available.user_interactions
genuine
indicates the user has high familiarity with the data they are providing, and that fraud is unlikely.neutral
indicates some signals are present in between risky
and genuine
, but there are not enough clear signals to determine an outcome.risky
indicates the user has low familiarity with the data they are providing, and that fraud is likely.no_data
indicates there is not sufficient information to give an accurate signal.genuine
, neutral
, risky
, no_data
fraud_ring_detected
yes
indicates that fraud ring activity was detected.no
indicates that fraud ring activity was not detected.no_data
indicates there was not enough information available to give an accurate signal.yes
, no
, no_data
bot_detected
yes
indicates that automated activity was detected.no
indicates that automated activity was not detected.no_data
indicates there was not enough information available to give an accurate signal.yes
, no
, no_data
email
email
attributes of risk check.is_deliverable
yes
, no
, no_data
breach_count
first_breached_at
date
last_breached_at
date
domain_registered_at
date
domain_is_free _provider
yes
, no
, no_data
domain_is_custom
yes
, no
, no_data
domain_is_disposable
yes
, no
, no_data
top_level_domain_is _suspicious
yes
, no
, no_data
linked_services
aboutme
, adobe
, adult_sites
, airbnb
, altbalaji
, amazon
, apple
, archiveorg
, atlassian
, bitmoji
, bodybuilding
, booking
, bukalapak
, codecademy
, deliveroo
, diigo
, discord
, disneyplus
, duolingo
, ebay
, envato
, eventbrite
, evernote
, facebook
, firefox
, flickr
, flipkart
, foursquare
, freelancer
, gaana
, giphy
, github
, google
, gravatar
, hubspot
, imgur
, instagram
, jdid
, kakao
, kommo
, komoot
, lastfm
, lazada
, line
, linkedin
, mailru
, microsoft
, myspace
, netflix
, nike
, ok
, patreon
, pinterest
, plurk
, quora
, qzone
, rambler
, rappi
, replit
, samsung
, seoclerks
, shopclues
, skype
, snapchat
, snapdeal
, soundcloud
, spotify
, starz
, strava
, taringa
, telegram
, tiki
, tokopedia
, treehouse
, tumblr
, twitter
, venmo
, viber
, vimeo
, vivino
, vkontakte
, wattpad
, weibo
, whatsapp
, wordpress
, xing
, yahoo
, yandex
, zalo
, zoho
phone
phone
attributes of risk check.linked_services
aboutme
, adobe
, adult_sites
, airbnb
, altbalaji
, amazon
, apple
, archiveorg
, atlassian
, bitmoji
, bodybuilding
, booking
, bukalapak
, codecademy
, deliveroo
, diigo
, discord
, disneyplus
, duolingo
, ebay
, envato
, eventbrite
, evernote
, facebook
, firefox
, flickr
, flipkart
, foursquare
, freelancer
, gaana
, giphy
, github
, google
, gravatar
, hubspot
, imgur
, instagram
, jdid
, kakao
, kommo
, komoot
, lastfm
, lazada
, line
, linkedin
, mailru
, microsoft
, myspace
, netflix
, nike
, ok
, patreon
, pinterest
, plurk
, quora
, qzone
, rambler
, rappi
, replit
, samsung
, seoclerks
, shopclues
, skype
, snapchat
, snapdeal
, soundcloud
, spotify
, starz
, strava
, taringa
, telegram
, tiki
, tokopedia
, treehouse
, tumblr
, twitter
, venmo
, viber
, vimeo
, vivino
, vkontakte
, wattpad
, weibo
, whatsapp
, wordpress
, xing
, yahoo
, yandex
, zalo
, zoho
devices
device
attributes of risk check.ip_proxy_type
none_detected
indicates the user is not on a detectable proxy network.tor
indicates the user was using a Tor browser, which sends encrypted traffic on a decentralized network and is somewhat similar to a VPN (Virtual Private Network).vpn
indicates the user is on a VPN (Virtual Private Network)web_proxy
indicates the user is on a web proxy server, which may allow them to conceal information such as their IP address or other identifying information.public_proxy
indicates the user is on a public web proxy server, which is similar to a web proxy but can be shared by multiple users. This may allow multiple users to appear as if they have the same IP address for instance.none_detected
, tor
, vpn
, web_proxy
, public_proxy
ip_spam_list_count
ip_timezone_offset
identity_abuse_signals
identity abuse
, e.g. stolen and synthetic identity fraud. These attributes are only available for US identities and some signals may not be available depending on what information was collected.synthetic_identity
Contains the following fields:
score
- A score from 0 to 100 indicating the likelihood that the user is a synthetic identity.score
stolen_identity
Contains the following fields:
score
- A score from 0 to 100 indicating the likelihood that the user is a stolen identity.score
verify_sms
verify_sms
step.status
verify_sms
step. This field will always have the same value as steps.verify_sms
.success
, failed
verifications
verify_sms
step. Each entry represents one user-submitted phone number. Phone number edits, and in some cases error handling due to edge cases like rate limiting, may generate additional verifications.status
pending
, success
, failed
, canceled
attempt
phone_number
delivery_attempt_count
solve_attempt_count
initially_sent_at
date-time
last_sent_at
date-time
redacted_at
date-time
watchlist_screening_id
beacon_user_id
redacted_at
date-time
next_cursor
request_id
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": 213 },14 "user": {15 "phone_number": "+12345678909",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 "date_of_birth": "1990-05-29",66 "address": {67 "street": "123 Main St. Unit 42",68 "city": "Pawnee",69 "region": "IN",70 "postal_code": "46001",71 "country": "US"72 },73 "name": {74 "given_name": "Leslie",75 "family_name": "Knope"76 }77 },78 "analysis": {79 "authenticity": "match",80 "image_quality": "high",81 "extracted_data": {82 "name":