action plaid_identity_verification_create {
label: "Create a new identity verification"
description: "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.\nIf 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.\n"
provider: plaid
method: POST
path: "/identity_verification/create"
encoding: json
input: {
type: "object"
description: "Request schema for '/identity_verification/create'"
required: ["gave_consent", "is_shareable", "template_id", "user"]
properties: {
client_id: {
type: "string"
description: "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."
}
gave_consent: {
type: "boolean"
description: "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.\n\nIf `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."
}
is_idempotent: {
type: "boolean"
description: "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`.\nIf 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`."
}
is_shareable: {
type: "boolean"
description: "A flag specifying whether you would like Plaid to expose a shareable URL for the verification being created."
}
secret: {
type: "string"
description: "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."
}
template_id: {
type: "string"
description: "ID of the associated Identity Verification template."
}
user: {
type: "object"
description: "User information collected outside of Link, most likely via your own onboarding process.\n\nEach of the following identity fields are optional:\n\n`email_address`\n\n`phone_number`\n\n`date_of_birth`\n\n`name`\n\n`address`\n\n`id_number`\n\nSpecifically, 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.\nProviding 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."
required: ["client_user_id"]
properties: {
address: {
type: "object"
description: "Home address for the user."
required: ["city", "country", "postal_code", "region", "street"]
properties: {
city: {
type: "string"
description: "City from the end user's address"
}
country: {
type: "string"
description: "Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form."
}
postal_code: {
type: "string"
description: "The postal code for the associated address. Between 2 and 10 alphanumeric characters. For US-based addresses this must be 5 numeric digits."
}
region: {
type: "string"
description: "An ISO 3166-2 subdivision code. Related terms would be \"state\", \"province\", \"prefecture\", \"zone\", \"subdivision\", etc."
}
street: {
type: "string"
description: "The primary street portion of an address. If the user has submitted their address, this field will always be filled."
}
street2: {
type: "string"
description: "Extra street information, like an apartment or suite number."
}
}
}
client_user_id: {
type: "string"
description: "An identifier to help you connect this object to your internal systems. For example, your database ID corresponding to this object."
}
date_of_birth: {
type: "string"
format: "date"
description: "A date in the format YYYY-MM-DD (RFC 3339 Section 5.6)."
}
email_address: {
type: "string"
format: "email"
description: "A valid email address."
}
id_number: {
type: "object"
description: "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."
required: ["type", "value"]
properties: {
type: {
type: "string"
description: "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](https://plaid.com/docs/identity-verification/hybrid-input-validation)."
enum: ["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"]
}
value: {
type: "string"
description: "Value of identity document value typed in by user. Alpha-numeric, with all formatting characters stripped."
}
}
}
name: {
type: "object"
description: "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."
required: ["family_name", "given_name"]
properties: {
family_name: {
type: "string"
description: "A string with at least one non-whitespace character, with a max length of 100 characters."
}
given_name: {
type: "string"
description: "A string with at least one non-whitespace character, with a max length of 100 characters."
}
}
}
phone_number: {
type: "string"
description: "A phone number in E.164 format."
}
}
}
}
}
output: {
type: "object"
description: "A identity verification attempt represents a customer's attempt to verify their identity, reflecting the required steps for completing the session, the results for each step, and information collected in the process."
required: ["client_user_id", "completed_at", "created_at", "documentary_verification", "id", "kyc_check", "previous_attempt_id", "redacted_at", "request_id", "shareable_url", "status", "steps", "template", "user", "watchlist_screening_id"]
properties: {
client_user_id: {
type: "string"
description: "An identifier to help you connect this object to your internal systems. For example, your database ID corresponding to this object."
}
completed_at: {
type: "string"
format: "date-time"
description: "An ISO8601 formatted timestamp."
}
created_at: {
type: "string"
format: "date-time"
description: "An ISO8601 formatted timestamp."
}
documentary_verification: {
type: "object"
description: "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`."
required: ["documents", "status"]
properties: {
documents: {
type: "array"
description: "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.\n\nNote: 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."
items: {
type: "object"
description: "Images, extracted data, and analysis from a user's identity document"
required: ["analysis", "attempt", "extracted_data", "images", "status", "redacted_at"]
properties: {
analysis: {
type: "object"
description: "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."
required: ["authenticity", "image_quality", "extracted_data"]
properties: {
authenticity: {
type: "string"
description: "High level summary of whether the document in the provided image matches the formatting rules and security checks for the associated jurisdiction.\n\nFor example, most identity documents have formatting rules like the following:\n\n\nThe image of the person's face must have a certain contrast in order to highlight skin tone\n\n\nThe subject in the document's image must remove eye glasses and pose in a certain way\n\n\nThe informational fields (name, date of birth, ID number, etc.) must be colored and aligned according to specific rules\n\n\nSecurity features like watermarks and background patterns must be present\n\nSo 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."
enum: ["match", "partial_match", "no_match", "no_data"]
}
extracted_data: {
type: "object"
description: "Analysis of the data extracted from the submitted document."
required: ["name", "date_of_birth", "expiration_date", "issuing_country"]
properties: {
date_of_birth: {
type: "string"
description: "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."
enum: ["match", "partial_match", "no_match"]
}
expiration_date: {
type: "string"
description: "A description of whether the associated document was expired when the verification was performed.\n\nNote: In the case where an expiration date is not present on the document or failed to be extracted, this value will be `no_data`."
enum: ["not_expired", "expired", "no_data"]
}
issuing_country: {
type: "string"
description: "A binary match indicator specifying whether the country that issued the provided document matches the country that the user separately provided to Plaid.\n\nNote: You can configure whether a `no_match` on `issuing_country` fails the `documentary_verification` by editing your Plaid Template."
enum: ["match", "no_match"]
}
name: {
type: "string"
description: "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."
enum: ["match", "partial_match", "no_match"]
}
}
}
image_quality: {
type: "string"
description: "A high level description of the quality of the image the user submitted.\n\nFor 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.\n\nNote: 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."
enum: ["high", "medium", "low"]
}
}
}
attempt: {
type: "number"
description: "The `attempt` field begins with 1 and increments with each subsequent document upload."
}
extracted_data: {
type: "object"
description: "Data extracted from a user-submitted document."
required: ["id_number", "category", "expiration_date", "issuing_country", "issuing_region"]
properties: {
category: {
type: "string"
description: "The type of identity document detected in the images provided. Will always be one of the following values:\n\n `drivers_license` - A driver's license for the associated country\n\n `id_card` - A general national identification card, distinct from driver's licenses\n\n `passport` - A passport for the associated country\n\n `residence_permit_card` - An identity document permitting a foreign citizen to temporarily reside in the associated country\n\n `resident_card` - An identity document permitting a foreign citizen to permanently reside in the associated country\n\nNote: 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`"
enum: ["drivers_license", "id_card", "passport", "residence_permit_card", "resident_card"]
}
expiration_date: {
type: "string"
format: "date"
description: "A date in the format YYYY-MM-DD (RFC 3339 Section 5.6)."
}
id_number: {
type: "string"
description: "Alpha-numeric ID number extracted via OCR from the user's document image."
}
issuing_country: {
type: "string"
description: "Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form."
}
issuing_region: {
type: "string"
description: "An ISO 3166-2 subdivision code. Related terms would be \"state\", \"province\", \"prefecture\", \"zone\", \"subdivision\", etc."
}
}
}
images: {
type: "object"
description: "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."
required: ["original_front", "original_back", "cropped_front", "cropped_back", "face"]
properties: {
cropped_back: {
type: "string"
description: "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."
}
cropped_front: {
type: "string"
description: "Temporary URL that expires after 60 seconds for downloading a cropped image containing just the front of the document."
}
face: {
type: "string"
description: "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."
}
original_back: {
type: "string"
description: "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."
}
original_front: {
type: "string"
description: "Temporary URL that expires after 60 seconds for downloading the uncropped original image of the front of the document."
}
}
}
redacted_at: {
type: "object"
additionalProperties: true
}
status: {
type: "string"
description: "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."
enum: ["success", "failed", "manually_approved"]
}
}
}
}
status: {
type: "string"
description: "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`."
}
}
}
id: {
type: "string"
description: "ID of the associated Identity Verification attempt."
}
kyc_check: {
type: "object"
description: "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`."
required: ["address", "date_of_birth", "id_number", "name", "phone_number", "status"]
properties: {
address: {
type: "object"
description: "Result summary object specifying how the `address` field matched."
required: ["po_box", "summary", "type"]
properties: {
po_box: {
type: "string"
description: "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."
enum: ["yes", "no", "no_data"]
}
summary: {
type: "string"
description: "An enum indicating the match type between data provided by user and data checked against an external data source.\n\n\n`match` indicates that the provided input data was a strong match against external data.\n\n`partial_match` indicates the data approximately matched against external data. For example, \"Knope\" vs. \"Knope-Wyatt\" for last name.\n\n`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.\n\n`no_data` indicates that Plaid was unable to find external data to compare against the provided input data.\n\n`no_input` indicates that Plaid was unable to perform a check because no information was provided for this field by the end user."
enum: ["match", "partial_match", "no_match", "no_data", "no_input"]
}
type: {
type: "string"
description: "Field describing whether the associated address is being used for commercial or residential purposes.\n\nNote: This value will be `no_data` when Plaid does not have sufficient data to determine the address's use."
enum: ["residential", "commercial", "no_data"]
}
}
}
date_of_birth: {
type: "object"
description: "Result summary object specifying how the `date_of_birth` field matched."
required: ["summary"]
properties: {
summary: {
type: "object"
additionalProperties: true
}
}
}
id_number: {
type: "object"
description: "Result summary object specifying how the `id_number` field matched."
required: ["summary"]
properties: {
summary: {
type: "object"
additionalProperties: true
}
}
}
name: {
type: "object"
description: "Result summary object specifying how the `name` field matched."
required: ["summary"]
properties: {
summary: {
type: "object"
additionalProperties: true
}
}
}
phone_number: {
type: "object"
description: "Result summary object specifying how the `phone` field matched."
required: ["summary"]
properties: {
summary: {
type: "object"
additionalProperties: true
}
}
}
status: {
type: "string"
description: "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`."
}
}
}
previous_attempt_id: {
type: "string"
description: "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."
}
redacted_at: {
type: "object"
additionalProperties: true
}
request_id: {
type: "string"
description: "A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive."
}
shareable_url: {
type: "string"
description: "A shareable URL that can be sent directly to the user to complete verification"
}
status: {
type: "string"
description: "The status of this Identity Verification attempt.\n\n\n`active` - The Identity Verification attempt is incomplete. The user may have completed part of the session, but has neither failed or passed.\n\n`success` - The Identity Verification attempt has completed, passing all steps defined to the associated Identity Verification template\n\n`failed` - The user failed one or more steps in the session and was told to contact support.\n\n`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.\n\n`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.\n\n`pending_review` - The Identity Verification attempt template was configured to perform a screening that had one or more hits needing review."
enum: ["active", "success", "failed", "expired", "canceled", "pending_review"]
}
steps: {
type: "object"
description: "Each step will be one of the following values:\n\n\n`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.\n\n`success` - The Identity Verification attempt has completed this step.\n\n`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.\n\n`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.\n\n`not_applicable` - This step will not be run for this session.\n\n`skipped` - The retry instructions that created this Identity Verification attempt specified that this step should be skipped.\n\n`expired` - This step had not yet been completed when the Identity Verification attempt as a whole expired.\n\n`canceled` - The Identity Verification attempt was canceled before the user completed this step.\n\n`pending_review` - The Identity Verification attempt template was configured to perform a screening that had one or more hits needing review.\n\n`manually_approved` - The step was manually overridden to pass by a team member in the dashboard.\n\n`manually_rejected` - The step was manually overridden to fail by a team member in the dashboard."
required: ["accept_tos", "documentary_verification", "kyc_check", "risk_check", "selfie_check", "verify_sms", "watchlist_screening"]
properties: {
accept_tos: {
type: "string"
description: "The status of a step in the identity verification process."
enum: ["success", "active", "failed", "waiting_for_prerequisite", "not_applicable", "skipped", "expired", "canceled", "pending_review", "manually_approved", "manually_rejected"]
}
documentary_verification: {
type: "object"
additionalProperties: true
}
kyc_check: {
type: "object"
additionalProperties: true
}
risk_check: {
type: "object"
additionalProperties: true
}
selfie_check: {
type: "object"
additionalProperties: true
}
verify_sms: {
type: "object"
additionalProperties: true
}
watchlist_screening: {
type: "object"
additionalProperties: true
}
}
}
template: {
type: "object"
description: "The resource ID and version number of the template configuring the behavior of a given identity verification."
required: ["id", "version"]
properties: {
id: {
type: "string"
description: "ID of the associated Identity Verification template."
}
version: {
type: "number"
description: "Version of the associated Identity Verification template."
}
}
}
user: {
type: "object"
description: "The identity data that was either collected from the user or provided via API in order to perform an identity verification."
required: ["address", "date_of_birth", "email_address", "id_number", "ip_address", "name"]
properties: {
address: {
type: "object"
description: "Even if an address has been collected, some fields may be null depending on the region's addressing system. For example:\n\nAddresses from the United Kingdom will not include a region\n\nAddresses from Hong Kong will not include postal code"
required: ["city", "country", "postal_code", "region", "street", "street2"]
properties: {
city: {
type: "string"
description: "City from the end user's address"
}
country: {
type: "object"
additionalProperties: true
}
postal_code: {
type: "string"
description: "The postal code for the associated address. Between 2 and 10 alphanumeric characters. For US-based addresses this must be 5 numeric digits."
}
region: {
type: "object"
additionalProperties: true
}
street: {
type: "string"
description: "The primary street portion of an address. If the user has submitted their address, this field will always be filled."
}
street2: {
type: "string"
description: "Extra street information, like an apartment or suite number."
}
}
}
date_of_birth: {
type: "object"
additionalProperties: true
}
email_address: {
type: "string"
format: "email"
description: "A valid email address."
}
id_number: {
type: "object"
description: "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."
required: ["type", "value"]
properties: {
type: {
type: "string"
description: "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](https://plaid.com/docs/identity-verification/hybrid-input-validation)."
enum: ["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"]
}
value: {
type: "string"
description: "Value of identity document value typed in by user. Alpha-numeric, with all formatting characters stripped."
}
}
}
ip_address: {
type: "string"
description: "An IPv4 or IPV6 address."
}
name: {
type: "object"
description: "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."
required: ["family_name", "given_name"]
properties: {
family_name: {
type: "string"
description: "A string with at least one non-whitespace character, with a max length of 100 characters."
}
given_name: {
type: "string"
description: "A string with at least one non-whitespace character, with a max length of 100 characters."
}
}
}
phone_number: {
type: "string"
description: "A phone number in E.164 format."
}
}
}
watchlist_screening_id: {
type: "string"
description: "ID of the associated screening."
}
}
}
}