Link endpoints
API reference for Link tokens and webhooks
This page covers the backend flow for creating and managing Link tokens. For the Link frontend, see Link docs.
Endpoints | |
---|---|
/link/token/create | Create a token for initializing a Link session |
/link/token/get | Get the public token and other details about a completed Link session |
See also | |
---|---|
/item/public_token/exchange | Exchange a public token for an access token |
/sandbox/public_token/create | Create a public token without the Link flow (Sandbox only) |
/sandbox/item/reset_login | Force an Item into an error state (Sandbox only) |
Webhooks | |
---|---|
ITEM_ADD_RESULT | An Item was added during a Link session |
EVENTS | Events were received from a Hosted Link session |
SESSION_FINISHED | The user has completed a Link session |
Endpoints
/link/token/create
Create Link Token
The /link/token/create
endpoint creates a link_token
, which is required as a parameter when initializing Link. Once Link has been initialized, it returns a public_token
. For most Plaid products, the public_token
is saved and exchanged for an access_token
via /item/public_token/exchange
as part of the main Link flow. For more details, see the Link flow overview.
A link_token
generated by /link/token/create
is also used to initialize other Link flows, such as the update mode flow for tokens with expired credentials, or the Identity Verification flow.
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.client_name
1
language
Supported languages are:
- Danish (
'da'
) - Dutch (
'nl'
) - English (
'en'
) - Estonian (
'et'
) - French (
'fr'
) - German (
'de'
) - Italian (
'it'
) - Latvian (
'lv'
) - Lithuanian (
'lt'
) - Norwegian (
'no'
) - Polish (
'pl'
) - Portuguese (
'pt'
) - Romanian (
'ro'
) - Spanish (
'es'
) - Swedish (
'sv'
)
When using a Link customization, the language configured here must match the setting in the customization, or the customization will not be applied.
1
country_codes
If using Identity Verification,
country_codes
should be set to the country where your company is based, not the country where your user is located. For all other products, country_codes
represents the location of your user's financial institution.If Link is launched with multiple country codes, only products that you are enabled for in all countries will be used by Link. Note that while all countries are enabled by default in Sandbox, in Production only US and Canada are enabled by default. To request access to European institutions, file a product access Support ticket via the Plaid dashboard.
If using a Link customization, make sure the country codes in the customization match those specified in
country_codes
, or the customization may not be applied.If using the Auth features Instant Match, Instant Micro-deposits, Same-day Micro-deposits, Automated Micro-deposits, or Database Insights,
country_codes
must be set to ['US']
.1
US
, GB
, ES
, NL
, FR
, IE
, CA
, DE
, IT
, PL
, DK
, NO
, SE
, EE
, LT
, LV
, PT
, BE
user
client_user_id
client_user_id
. It is currently used as a means of searching logs for the given user in the Plaid Dashboard.1
legal_name
name
given_name
family_name
phone_number
email_address
date_of_birth
date
address
street
street2
city
region
postal_code
country
id_number
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
products
balance
is not a valid value, the Balance product does not require explicit initialization and will automatically be initialized when any other product is initialized.The products specified here will determine which institutions will be available to your users in Link. Only institutions that support all requested products can be selected; a if a user attempts to select an institution that does not support a listed product, a "Connectivity not supported" error message will appear in Link. To maximize the number of institutions available, initialize Link with the minimal product set required for your use case.
Additional products can be included via the
optional_products
or required_if_supported_products
fields. Products can also be be initialized by calling the endpoint after obtaining an access token; this may require the product to be listed in the additional_consented_products
array. For details, see Choosing when to initialize products.Note that, unless you have opted to disable Instant Match support, institutions that support Instant Match will also be shown in Link if
auth
is specified as a product, even though these institutions do not contain auth
in their product array.In Production, you will be billed for each product that you specify when initializing Link. Note that a product cannot be removed from an Item once the Item has been initialized with that product. To stop billing on an Item for subscription-based products, such as Liabilities, Investments, and Transactions, remove the Item via
/item/remove
.assets
, auth
, balance_plus
, beacon
, employment
, identity
, income_verification
, identity_verification
, investments
, liabilities
, payment_initiation
, standing_orders
, transactions
, transfer
, signal
, cra_base_report
, cra_income_insights
, cra_partner_insights
, cra_cashflow_insights
, layer
required_if_supported _products
There should be no overlap between this array and the
products
, optional_products
, or additional_consented_products
arrays. The products
array must have at least one product.For more details on using this feature, see Required if Supported Products.
auth
, identity
, investments
, liabilities
, transactions
, statements
optional_products
There should be no overlap between this array and the
products
, required_if_supported_products
, or additional_consented_products
arrays. The products
array must have at least one product.For more details on using this feature, see Optional Products.
auth
, identity
, investments
, liabilities
, signal
, statements
, transactions
additional_consented _products
balance
is not a valid value, the Balance product does not require explicit initialization and will automatically have consent collected.Institutions that do not support these products will still be shown in Link.
There should be no overlap between this array and the
products
or required_if_supported_products
arrays.auth
, balance_plus
, identity
, investments
, liabilities
, transactions
, signal
webhook
access_token
access_token
associated with the Item to update or reference, used when updating, modifying, or accessing an existing access_token
. Used when launching Link in update mode, when completing the Same-day (manual) Micro-deposit flow, or (optionally) when initializing Link for a returning user as part of the Transfer UI flow.1
link_customization _name
default
customization will be used. When using a Link customization, the language in the customization must match the language selected via the language
parameter, and the countries in the customization should match the country codes selected via country_codes
.redirect_uri
redirect_uri
should not contain any query parameters. When used in Production, must be an https URI. To specify any subdomain, use *
as a wildcard character, e.g. https://*.example.com/oauth.html
. Note that any redirect URI must also be added to the Allowed redirect URIs list in the developer dashboard. If initializing on Android, android_package_name
must be specified instead and redirect_uri
should be left blank.android_package_name
link_token
to initialize Link on Android. Any package name specified here must also be added to the Allowed Android package names setting on the developer dashboard. When creating a link_token
for initializing Link on other platforms, android_package_name
must be left blank and redirect_uri
should be used instead.institution_data
routing_number
account_filters
products
parameter of /link/token/create
, and, if auth
is specified in the products
array, will also filter out accounts other than checking
and savings
accounts on the Account Select pane. You can further limit the accounts shown in Link by using account_filters
to specify the account subtypes to be shown in Link. Only the specified subtypes will be shown. This filtering applies to both the Account Select view (if enabled) and the Institution Select view. Institutions that do not support the selected subtypes will be omitted from Link. To indicate that all subtypes should be shown, use the value "all"
. If the account_filters
filter is used, any account type for which a filter is not specified will be entirely omitted from Link. For a full list of valid types and subtypes, see the Account schema.The filter may or may not impact the list of accounts shown by the institution in the OAuth account selection flow, depending on the specific institution. If the user selects excluded account subtypes in the OAuth flow, these accounts will not be added to the Item. If the user selects only excluded account subtypes, the link attempt will fail and the user will be prompted to try again.
depository
depository
-type accountsaccount_subtypes
checking
, savings
, hsa
, cd
, money market
, paypal
, prepaid
, cash management
, ebt
, all
credit
credit
-type accountsaccount_subtypes
credit card
, paypal
, all
loan
loan
-type accountsaccount_subtypes
auto
, business
, commercial
, construction
, consumer
, home equity
, loan
, mortgage
, line of credit
, student
, other
, all
investment
investment
-type accounts (or brokerage
-type accounts for API versions 2018-05-22 and earlier).account_subtypes
529
, 401a
, 401k
, 403B
, 457b
, brokerage
, cash isa
, crypto exchange
, education savings account
, fixed annuity
, gic
, health reimbursement arrangement
, hsa
, ira
, isa
, keogh
, lif
, life insurance
, lira
, lrif
, lrsp
, mutual fund
, non-custodial wallet
, non-taxable brokerage account
, other
, other annuity
, other insurance
, pension
, prif
, profit sharing plan
, qshr
, rdsp
, resp
, retirement
, rlif
, roth
, roth 401k
, rrif
, rrsp
, sarsep
, sep ira
, simple ira
, sipp
, stock plan
, tfsa
, trust
, ugma
, utma
, variable annuity
, all
other
other
-type accountsaccount_subtypes
other
, all
institution_id
payment_initiation
payment_initiation
is included in the products
array. Either payment_id
or consent_id
must be provided.payment_id
payment_id
provided by the /payment_initiation/payment/create
endpoint.consent_id
consent_id
provided by the /payment_initiation/consent/create
endpoint.income_verification
income_verification
is included in the products
array.asset_report_id
asset_report_id
of an asset report associated with the user, as provided by /asset_report/create
. Providing an asset_report_id
is optional and can be used to verify the user through a streamlined flow. If provided, the bank linking flow will be skipped.access_tokens
transactions
product was not initialized for these Items during link, it will be initialized after this Link session.This field should only be used with the
payroll
income source type.income_source_types
bank
and payroll
. Currently you can only specify one of these options.bank
, payroll
bank_income
income_verification
is included in the products
array and bank
is specified in income_source_types
.days_requested
1
731
enable_multiple_items
enable_multi_item_link
setting, which supports all products.false
payroll_income
flow_types
payroll_digital_income
, payroll_document_income
is_update_mode
false
item_id_to_update
parsing_config
ocr
, risk_signals
stated_income_sources
employer
category
OTHER
, SALARY
, UNEMPLOYMENT
, CASH
, GIG_ECONOMY
, RENTAL
, CHILD_SUPPORT
, MILITARY
, RETIREMENT
, LONG_TERM_DISABILITY
, BANK_INTEREST
pay_per_cycle
double
pay_annual
double
pay_type
GROSS
, NET
, or UNKNOWN
for a specified income sourceUNKNOWN
, GROSS
, NET
pay_frequency
UNKNOWN
, WEEKLY
, BIWEEKLY
, SEMI_MONTHLY
, MONTHLY
cra_options
days_requested
1
730
partner_insights
prism_products
insights
, scores
base_report
client_report_id
cashflow_insights
plaid_check_score _version
attributes_version
v1.0
consumer_report _permissible_purpose
ACCOUNT_REVIEW_CREDIT
: In connection with a consumer credit transaction for the review or collection of an account pursuant to FCRA Section 604(a)(3)(A).ACCOUNT_REVIEW_NON_CREDIT
: For a legitimate business need of the information to review a non-credit account provided primarily for personal, family, or household purposes to determine whether the consumer continues to meet the terms of the account pursuant to FCRA Section 604(a)(3)(F)(2).EMPLOYMENT
: For employment purposes pursuant to FCRA 604(a)(3)(B), including hiring, retention and promotion purposes.EXTENSION_OF_CREDIT
: In connection with a credit transaction initiated by and involving the consumer pursuant to FCRA Section 604(a)(3)(A).LEGITIMATE_BUSINESS_NEED_TENANT_SCREENING
: For a legitimate business need in connection with a business transaction initiated by the consumer primarily for personal, family, or household purposes in connection with a property rental assessment pursuant to FCRA Section 604(a)(3)(F)(i).LEGITIMATE_BUSINESS_NEED_OTHER
: For a legitimate business need in connection with a business transaction made primarily for personal, family, or household initiated by the consumer pursuant to FCRA Section 604(a)(3)(F)(i).WRITTEN_INSTRUCTION_PREQUALIFICATION
: In accordance with the written instructions of the consumer pursuant to FCRA Section 604(a)(2), to evaluate an application’s profile to make an offer to the consumer.WRITTEN_INSTRUCTION_OTHER
: In accordance with the written instructions of the consumer pursuant to FCRA Section 604(a)(2), such as when an individual agrees to act as a guarantor or assumes personal liability for a consumer, business, or commercial loan.ACCOUNT_REVIEW_CREDIT
, ACCOUNT_REVIEW_NON_CREDIT
, EMPLOYMENT
, EXTENSION_OF_CREDIT
, LEGITIMATE_BUSINESS_NEED_TENANT_SCREENING
, LEGITIMATE_BUSINESS_NEED_OTHER
, WRITTEN_INSTRUCTION_PREQUALIFICATION
, WRITTEN_INSTRUCTION_OTHER
auth
auth_type_select _enabled
false
.automated _microdeposits_enabled
false
.instant_match_enabled
false
.same_day _microdeposits_enabled
false
.instant_microdeposits _enabled
false
; default behavior for Plaid teams created before that date is true
.reroute_to_credentials
OPTIONAL
.OFF
, OPTIONAL
, FORCED
database_match_enabled
false
.database_insights _enabled
false
.flow_type
auth_type_select_enabled
.FLEXIBLE_AUTH
sms_microdeposits _verification_enabled
true
.transfer
intent_id
id
returned by the /transfer/intent/create
endpoint.authorization_id
id
returned by the /transfer/authorization/create
endpoint. Used to indicate Link session to complete required user action in order to make a decision for the authorization. If set, access_token
can be omitted.update
account_selection _enabled
true
, enables update mode with Account Select for institutions in the US and Canada that do not use OAuth, or that use OAuth but do not have their own account selection flow. For institutions in the US that have an OAuth account selection flow (i.e. most OAuth-enabled institutions), update mode with Account Select will always be enabled, regardless of the value of this field.false
reauthorization _enabled
user
true
, a user_token
must also be provided, and Link will open in update mode for the given user.false
item_ids
item_id
s associated with the user to be updated in update mode. If empty or null
, this field will default to initializing update mode for the most recent unhealthy Item associated with the user. A user_token
must also be provided to use this field.identity_verification
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
statements
start_date
user_token
/user/create
. Any Item created during the Link session will be associated with the user.investments
allow_unverified _crypto_wallets
true
, allow self-custody crypto wallets to be added without requiring signature verification. Defaults to false
.allow_manual_entry
true
, allow users to manually enter Investments account and holdings information. Defaults to false
.hosted_link
delivery_method
user.phone_number
.
'email' will deliver via email. Must pass user.email_address
. In the Sandbox environment, this field will be ignored; use the Production environment to test Link Delivery instead.sms
, email
completion_redirect _uri
url_lifetime_seconds
is_mobile_app
AsWebAuthenticationSession
/ SFSafariViewController
or Android Custom Tab).false
transactions
days_requested
Customers using Recurring Transactions should request at least 180 days of history for optimal results.
1
730
90
identity
is_document_upload
account_ids
account_ids
parsing_configs
ocr
and risk_signals
. If parsing configurations are omitted, defaults to ocr
ocr
, risk_signals
enable_multi_item_link
true
, enable linking multiple items in the same Link session. Defaults to false
.1const request: LinkTokenCreateRequest = {2 loading_sample: true3};4try {5 const response = await plaidClient.linkTokenCreate(request);6 const linkToken = response.data.link_token;7} catch (error) {8 // handle error9}
Response fields and example
link_token
link_token
, which can be supplied to Link in order to initialize it and receive a public_token
, which can be exchanged for an access_token
.expiration
link_token
, in ISO 8601 format. A link_token
created to generate a public_token
that will be exchanged for a new access_token
expires after 4 hours. A link_token
created for an existing Item (such as when updating an existing access_token
by launching Link in update mode) expires after 30 minutes.date-time
request_id
hosted_link_url
1{2 "link_token": "link-sandbox-af1a0311-da53-4636-b754-dd15cc058176",3 "expiration": "2020-03-27T12:56:34Z",4 "request_id": "XQVgFigpGHXkb0b"5}
Was this helpful?
/link/token/get
Get Link Token
The /link/token/get
endpoint gets information about a Link session, including all callbacks fired during the session along with their metadata, including the public token. This endpoint is used with Link flows that don't provide a public token via frontend callbacks, such as the Hosted Link flow and the Multi-Item Link flow. It also can be useful for debugging purposes.
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.link_token
link_token
from a previous invocation of /link/token/create
1const request: LinkTokenGetRequest = {2 link_token: linkToken,3};4try {5 const response = await plaidClient.linkTokenGet(request);6} catch (error) {7 // handle error8}
Response fields and example
link_token
link_token
, which can be supplied to Link in order to initialize it and receive a public_token
, which can be exchanged for an access_token
.created_at
expiration
link_sessions
link_token
. Session data will be provided for up to six hours after the session has ended.link_session_id
started_at
finished_at
date-time
on_success
results.item_add_result
, which can support multiple public tokens in a single Link session.public_token
metadata
institution
null
.name
'Wells Fargo'
institution_id
accounts
accounts
will only include selected accounts.id
account_id
name
mask
type
subtype
verification_status
pending_automatic_verification
: The Item is pending automatic verificationpending_manual_verification
: The Item is pending manual micro-deposit verification. Items remain in this state until the user successfully verifies the code.automatically_verified
: The Item has successfully been automatically verifiedmanually_verified
: The Item has successfully been manually verifiedverification_expired
: Plaid was unable to automatically verify the deposit within 7 calendar days and will no longer attempt to validate the Item. Users may retry by submitting their information again through Link.verification_failed
: The Item failed manual micro-deposit verification because the user exhausted all 3 verification attempts. Users may retry by submitting their information again through Link.database_matched
: The Item has successfully been verified using Plaid's data sources.database_insights_pending
: The Database Insights result is pending and will be available upon Auth request. Note: Database Insights is currently a beta feature, please contact your account manager for more information.null
: Neither micro-deposit-based verification nor database verification are being used for the Item.class_type
business
or personal
account.link_session_id
transfer_status
COMPLETE
– The transfer was completed.INCOMPLETE
– The transfer could not be completed. For help, see Troubleshooting transfers.
COMPLETE
, INCOMPLETE
, null
on_exit
error
error_code
and categorized by error_type
. Use these in preference to HTTP status codes to identify and handle specific errors. HTTP status codes are set and provide the broadest categorization of errors: 4xx codes are for developer- or user-related errors, and 5xx codes are for Plaid-related errors, and the status will be 2xx in non-error cases. An Item with a non-null
error object will only be part of an API response when calling /item/get
to view Item status. Otherwise, error fields will be null
if no error has occurred; if an error has occurred, an error code will be returned instead.error_type
INVALID_REQUEST
, INVALID_RESULT
, INVALID_INPUT
, INSTITUTION_ERROR
, RATE_LIMIT_EXCEEDED
, API_ERROR
, ITEM_ERROR
, ASSET_REPORT_ERROR
, RECAPTCHA_ERROR
, OAUTH_ERROR
, PAYMENT_ERROR
, BANK_TRANSFER_ERROR
, INCOME_VERIFICATION_ERROR
, MICRODEPOSITS_ERROR
, SANDBOX_ERROR
, PARTNER_ERROR
, TRANSACTIONS_ERROR
, TRANSACTION_ERROR
, TRANSFER_ERROR
error_code
error_code_reason
null
will be returned otherwise. Safe for programmatic use.Possible values:
OAUTH_INVALID_TOKEN
: The user’s OAuth connection to this institution has been invalidated.OAUTH_CONSENT_EXPIRED
: The user's access consent for this OAuth connection to this institution has expired.OAUTH_REVOKED_TOKEN
: The user’s OAuth connection to this institution is invalid because the user revoked their connection.error_message
display_message
null
if the error is not related to user action.This may change over time and is not safe for programmatic use.
request_id
causes
causes
will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified.causes
will only be provided for the error_type
ASSET_REPORT_ERROR
. causes
will also not be populated inside an error nested within a warning
object.status
documentation_url
suggested_action
metadata
institution
null
.name
Wells Fargo
institution_id
status
requires_questions
requires_selections
requires_code
choose_device
requires_credentials
requires_account _selection
requires_oauth
institution_not_found
institution_not _supported
link_session_id
request_id
exit
error
error_code
and categorized by error_type
. Use these in preference to HTTP status codes to identify and handle specific errors. HTTP status codes are set and provide the broadest categorization of errors: 4xx codes are for developer- or user-related errors, and 5xx codes are for Plaid-related errors, and the status will be 2xx in non-error cases. An Item with a non-null
error object will only be part of an API response when calling /item/get
to view Item status. Otherwise, error fields will be null
if no error has occurred; if an error has occurred, an error code will be returned instead.error_type
INVALID_REQUEST
, INVALID_RESULT
, INVALID_INPUT
, INSTITUTION_ERROR
, RATE_LIMIT_EXCEEDED
, API_ERROR
, ITEM_ERROR
, ASSET_REPORT_ERROR
, RECAPTCHA_ERROR
, OAUTH_ERROR
, PAYMENT_ERROR
, BANK_TRANSFER_ERROR
, INCOME_VERIFICATION_ERROR
, MICRODEPOSITS_ERROR
, SANDBOX_ERROR
, PARTNER_ERROR
, TRANSACTIONS_ERROR
, TRANSACTION_ERROR
, TRANSFER_ERROR
error_code
error_code_reason
null
will be returned otherwise. Safe for programmatic use.Possible values:
OAUTH_INVALID_TOKEN
: The user’s OAuth connection to this institution has been invalidated.OAUTH_CONSENT_EXPIRED
: The user's access consent for this OAuth connection to this institution has expired.OAUTH_REVOKED_TOKEN
: The user’s OAuth connection to this institution is invalid because the user revoked their connection.error_message
display_message
null
if the error is not related to user action.This may change over time and is not safe for programmatic use.
request_id
causes
causes
will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified.causes
will only be provided for the error_type
ASSET_REPORT_ERROR
. causes
will also not be populated inside an error nested within a warning
object.status
documentation_url
suggested_action
metadata
institution
null
.name
Wells Fargo
institution_id
status
requires_questions
requires_selections
requires_code
choose_device
requires_credentials
requires_account _selection
requires_oauth
institution_not_found
institution_not _supported
link_session_id
request_id
events
event_name
event_id
event_metadata
error_code
ERROR
, EXIT
.error_message
ERROR
, EXIT
.error_type
ERROR
, EXIT
.exit_status
EXIT
.institution_id
institution_name
institution_search _query
SEARCH_INSTITUTION
.request_id
mfa_type
SUBMIT_MFA
and TRANSITION_VIEW
when viewname is MFA
.view_name
TRANSITION_VIEW
.selection
phoneotp
or password
; if selection is used to describe the selected Auth Type Select flow, then possible values are flow_type_manual
or flow_type_instant
. Emitted by: MATCHED_SELECT_VERIFY_METHOD
and SELECT_AUTH_TYPE
.brand_name
match_reason
returning_user
or routing_number
. Emitted by: MATCHED_SELECT_INSTITUTION
.routing_number
SUBMIT_ROUTING_NUMBER
.account_number_mask
account_number_mask
is empty. Emitted by SUBMIT_ACCOUNT_NUMBER
.results
item_add_results
public_token
accounts
accounts
will only include selected accounts.id
account_id
name
mask
type
subtype
verification_status
pending_automatic_verification
: The Item is pending automatic verificationpending_manual_verification
: The Item is pending manual micro-deposit verification. Items remain in this state until the user successfully verifies the code.automatically_verified
: The Item has successfully been automatically verifiedmanually_verified
: The Item has successfully been manually verifiedverification_expired
: Plaid was unable to automatically verify the deposit within 7 calendar days and will no longer attempt to validate the Item. Users may retry by submitting their information again through Link.verification_failed
: The Item failed manual micro-deposit verification because the user exhausted all 3 verification attempts. Users may retry by submitting their information again through Link.database_matched
: The Item has successfully been verified using Plaid's data sources.database_insights_pending
: The Database Insights result is pending and will be available upon Auth request. Note: Database Insights is currently a beta feature, please contact your account manager for more information.null
: Neither micro-deposit-based verification nor database verification are being used for the Item.class_type
business
or personal
account.institution
null
.name
'Wells Fargo'
institution_id
cra_item_add_results
item_id
item_id
is always unique; linking the same account at the same institution twice will result in two Items with different item_id
values. The item_id
is case-sensitive.accounts
accounts
will only include selected accounts.id
account_id
name
mask
type
subtype
verification_status
pending_automatic_verification
: The Item is pending automatic verificationpending_manual_verification
: The Item is pending manual micro-deposit verification. Items remain in this state until the user successfully verifies the code.automatically_verified
: The Item has successfully been automatically verifiedmanually_verified
: The Item has successfully been manually verifiedverification_expired
: Plaid was unable to automatically verify the deposit within 7 calendar days and will no longer attempt to validate the Item. Users may retry by submitting their information again through Link.verification_failed
: The Item failed manual micro-deposit verification because the user exhausted all 3 verification attempts. Users may retry by submitting their information again through Link.database_matched
: The Item has successfully been verified using Plaid's data sources.database_insights_pending
: The Database Insights result is pending and will be available upon Auth request. Note: Database Insights is currently a beta feature, please contact your account manager for more information.null
: Neither micro-deposit-based verification nor database verification are being used for the Item.class_type
business
or personal
account.institution
null
.name
'Wells Fargo'
institution_id
bank_income_results
status
APPROVED
: User has approved and verified their incomeNO_DEPOSITS_FOUND
: We attempted, but were unable to find any income in the connected account.USER_REPORTED_NO_INCOME
: The user explicitly indicated that they don't receive income in the connected account.STARTED
: The user began the bank income portion of the link flow.INTERNAL_ERROR
: The user encountered an internal error.APPROVED
, NO_DEPOSITS_FOUND
, USER_REPORTED_NO_INCOME
item_id
item_id
is always unique; linking the same account at the same institution twice will result in two Items with different item_id
values. Like all Plaid identifiers, the item_id
is case-sensitive.institution
null
.name
'Wells Fargo'
institution_id
payroll_income_results
num_paystubs_retrieved
num_w2s_retrieved
institution
null
.name
'Wells Fargo'
institution_id
document_income _results
num_paystubs_uploaded
num_w2s_uploaded
num_bank_statements _uploaded
num_1099s_uploaded
metadata
/link/token/create
call.initial_products
products
specified in the /link/token/create
call.assets
, auth
, employment
, identity
, income_verification
, identity_verification
, investments
, liabilities
, payment_initiation
, standing_orders
, transactions
, transfer
webhook
webhook
specified in the /link/token/create
call.country_codes
country_codes
specified in the /link/token/create
call.US
, GB
, ES
, NL
, FR
, IE
, CA
, DE
, IT
, PL
, DK
, NO
, SE
, EE
, LT
, LV
, PT
, BE
language
language
specified in the /link/token/create
call.institution_data
routing_number
account_filters
account_filters
specified in the original call to /link/token/create
.depository
depository
-type accountsaccount_subtypes
checking
, savings
, hsa
, cd
, money market
, paypal
, prepaid
, cash management
, ebt
, all
credit
credit
-type accountsaccount_subtypes
credit card
, paypal
, all
loan
loan
-type accountsaccount_subtypes
auto
, business
, commercial
, construction
, consumer
, home equity
, loan
, mortgage
, line of credit
, student
, other
, all
investment
investment
-type accounts (or brokerage
-type accounts for API versions 2018-05-22 and earlier).account_subtypes
529
, 401a
, 401k
, 403B
, 457b
, brokerage
, cash isa
, crypto exchange
, education savings account
, fixed annuity
, gic
, health reimbursement arrangement
, hsa
, ira
, isa
, keogh
, lif
, life insurance
, lira
, lrif
, lrsp
, mutual fund
, non-custodial wallet
, non-taxable brokerage account
, other
, other annuity
, other insurance
, pension
, prif
, profit sharing plan
, qshr
, rdsp
, resp
, retirement
, rlif
, roth
, roth 401k
, rrif
, rrsp
, sarsep
, sep ira
, simple ira
, sipp
, stock plan
, tfsa
, trust
, ugma
, utma
, variable annuity
, all
redirect_uri
redirect_uri
specified in the /link/token/create
call.client_name
client_name
specified in the /link/token/create
call.user_token
request_id
1{2 "created_at": "2024-07-29T20:22:21Z",3 "expiration": "2024-07-29T20:52:22Z",4 "link_sessions": [5 {6 "events": [7 {8 "event_id": "8b2b5d28-79ec-468b-bbce-f8bd34be635a",9 "event_metadata": {10 "institution_id": "ins_20",11 "institution_name": "Citizens Bank",12 "request_id": "Nnclj9HntPMu5dm"13 },14 "event_name": "HANDOFF",15 "timestamp": "2024-07-29T20:23:59Z"16 },17 {18 "event_id": "12a888e0-da26-4c38-8ded-2992bc78c246",19 "event_metadata": {20 "request_id": "Nnclj9HntPMu5dm"21 },22 "event_name": "TRANSITION_VIEW",23 "timestamp": "2024-07-29T20:23:59Z"24 },25 {26 "event_id": "6557bdf1-a20a-43b0-8fed-c8b671e2f478",27 "event_metadata": {28 "institution_id": "ins_20",29 "institution_name": "Citizens Bank",30 "request_id": "sR4EGcU8zniznXi"31 },32 "event_name": "TRANSITION_VIEW",33 "timestamp": "2024-07-29T20:23:56Z"34 },35 {36 "event_id": "c6745f4c-d8fa-4103-8a65-7b995c60809e",37 "event_metadata": {38 "institution_id": "ins_20",39 "institution_name": "Citizens Bank",40 "request_id": "4LYDWkxfJ0htDA4"41 },42 "event_name": "SUBMIT_CREDENTIALS",43 "timestamp": "2024-07-29T20:23:55Z"44 },45 {46 "event_id": "2610fa06-e765-4c9e-8948-63048d451dbf",47 "event_metadata": {48 "institution_id": "ins_20",49 "institution_name": "Citizens Bank",50 "request_id": "4LYDWkxfJ0htDA4"51 },52 "event_name": "TRANSITION_VIEW",53 "timestamp": "2024-07-29T20:23:23Z"54 },55 {56 "event_id": "54b87deb-60a7-4f50-9326-293840090b72",57 "event_metadata": {58 "institution_id": "ins_20",59 "institution_name": "Citizens Bank",60 "request_id": "FTEFiPeL9OstwL4"61 },62 "event_name": "SELECT_INSTITUTION",63 "timestamp": "2024-07-29T20:23:23Z"64 },65 {66 "event_id": "6b285180-0bac-4ccc-bec0-d4ed75c253d2",67 "event_metadata": {68 "request_id": "FTEFiPeL9OstwL4"69 },70 "event_name": "TRANSITION_VIEW",71 "timestamp": "2024-07-29T20:23:20Z"72 },73 {74 "event_id": "239a6000-da50-4319-99f7-919378b7db53",75 "event_metadata": {76 "request_id": "WFgwgGivjBbwOb9"77 },78 "event_name": "TRANSITION_VIEW",79 "timestamp": "2024-07-29T20:23:17Z"80 },81 {82 "event_id": "0a523744-5003-4578-8414-c87e06ef8ca9",83 "event_metadata": {84 "institution_id": "ins_127989",85 "institution_name": "Bank of America",86 "request_id": "WFgwgGivjBbwOb9"87 },88 "event_name": "HANDOFF",89 "timestamp": "2024-07-29T20:23:17Z"90 },91 {92 "event_id": "ff44d52a-51ef-4987-b7d0-b6497dfa93cd",93 "event_metadata": {94 "institution_id": "ins_127989",95 "institution_name": "Bank of America",96 "request_id": "uqA0Vq8zuKlsB2y"97 },98 "event_name": "TRANSITION_VIEW",99 "timestamp": "2024-07-29T20:23:14Z"100 },101 {102 "event_id": "e0d7c1dc-8e7e-4361-893f-d6c2d2f050ab",103 "event_metadata": {104 "institution_id": "ins_127989",105 "institution_name": "Bank of America",106 "request_id": "dTGtMHbK21BLrsp"107 },108 "event_name": "OPEN_OAUTH",109 "timestamp": "2024-07-29T20:22:49Z"110 },111 {112 "event_id": "de87a1c0-666e-4d95-88d8-1163f6bf20f1",113 "event_metadata": {114 "institution_id": "ins_127989",115 "institution_name": "Bank of America",116 "request_id": "dTGtMHbK21BLrsp"117 },118 "event_name": "TRANSITION_VIEW",119 "timestamp": "2024-07-29T20:22:47Z"120 },121 {122 "event_id": "6edc2c59-96cd-4dee-a86b-140ddfd3076e",123 "event_metadata": {124 "institution_id": "ins_127989",125 "institution_name": "Bank of America",126 "request_id": "BxBukZsBEmxZw0I"127 },128 "event_name": "SELECT_INSTITUTION",129 "timestamp": "2024-07-29T20:22:46Z"130 },131 {132 "event_id": "d176ab57-26d2-45ee-a0fe-67daf0cf0cb0",133 "event_metadata": {134 "request_id": "BxBukZsBEmxZw0I"135 },136 "event_name": "TRANSITION_VIEW",137 "timestamp": "2024-07-29T20:22:43Z"138 },139 {140 "event_id": "b8be9c3d-7ac5-4851-bd92-0638cb63bdeb",141 "event_metadata": {142 "request_id": "UtqR09RKzJ1gcEx"143 },144 "event_name": "SKIP_SUBMIT_PHONE",145 "timestamp": "2024-07-29T20:22:42Z"146 },147 {148 "event_id": "7144cca7-533b-4dfc-81ed-f78a750ba95f",149 "event_metadata": {150 "request_id": "UtqR09RKzJ1gcEx"151 },152 "event_name": "TRANSITION_VIEW",153 "timestamp": "2024-07-29T20:22:40Z"154 },155 {156 "event_id": "e6a6dcc0-6bbf-4871-8d59-0c3a5eccff53",157 "event_metadata": {158 "request_id": "FTiagIVmxfqbevM"159 },160 "event_name": "TRANSITION_VIEW",161 "timestamp": "2024-07-29T20:22:39Z"162 }163 ],164 "finished_at": "2024-07-29T20:24:05.330312653Z",165 "link_session_id": "43face8b-a5c2-42a4-adec-4a4ec589eb46",166 "on_success": {167 "metadata": {168 "accounts": [169 {170 "class_type": null,171 "id": "DXzZ94ZG9vhaZy8BvyZRSQ4jJwwlkNS3RwoeX",172 "mask": "0000",173 "name": "Plaid Checking",174 "subtype": "checking",175 "type": "depository",176 "verification_status": null177 },178 {179 "class_type": null,180 "id": "VJyR7wRm79TNGEKxpEG9fjpJ1mmM5Bt9ymVkR",181 "mask": "1111",182 "name": "Plaid Saving",183 "subtype": "savings",184 "type": "depository",185 "verification_status": null186 },187 {188 "class_type": null,189 "id": "wZXnexn1eoH6LNWmMNL4hqkPB55ndjHPRNp93",190 "mask": "9999",191 "name": "Plaid Business Credit Card",192 "subtype": "credit card",193 "type": "credit",194 "verification_status": null195 }196 ],197 "institution": {198 "institution_id": "ins_127989",199 "name": "Bank of America"200 },201 "link_session_id": "43face8b-a5c2-42a4-adec-4a4ec589eb46",202 "transfer_status": null203 },204 "public_token": "public-sandbox-3b9687f0-3abd-4913-9889-f0ba816d4a3a"205 },206 "results": {207 "item_add_results": [208 {209 "accounts": [210 {211 "class_type": null,212 "id": "DXzZ94ZG9vhaZy8BvyZRSQ4jJwwlkNS3RwoeX",213 "mask": "0000",214 "name": "Plaid Checking",215 "subtype": "checking",216 "type": "depository",217 "verification_status": null218 },219 {220 "class_type": null,221 "id": "VJyR7wRm79TNGEKxpEG9fjpJ1mmM5Bt9ymVkR",222 "mask": "1111",223 "name": "Plaid Saving",224 "subtype": "savings",225 "type": "depository",226 "verification_status": null227 },228 {229 "class_type": null,230 "id": "wZXnexn1eoH6LNWmMNL4hqkPB55ndjHPRNp93",231 "mask": "9999",232 "name": "Plaid Business Credit Card",233 "subtype": "credit card",234 "type": "credit",235 "verification_status": null236 }237 ],238 "institution": {239 "institution_id": "ins_127989",240 "name": "Bank of America"241 },242 "public_token": "public-sandbox-3b9687f0-3abd-4913-9889-f0ba816d4a3a"243 },244 {245 "accounts": [246 {247 "class_type": null,248 "id": "qvqrX8gDvxCdyvvgGkKzSNPzDwaQGjFgyQk5Z",249 "mask": "4007",250 "name": "Checking",251 "subtype": "checking",252 "type": "depository",253 "verification_status": null254 }255 ],256 "institution": {257 "institution_id": "ins_20",258 "name": "Citizens Bank"259 },260 "public_token": "public-sandbox-44ba202e-bf6b-45c6-a5ba-d526765626a9"261 }262 ]263 },264 "started_at": "2024-07-29T20:22:36.522196741Z"265 }266 ],267 "link_token": "link-sandbox-e7b6956c-1522-4823-85d2-c4ca74251949",268 "metadata": {269 "client_name": "Wonderwallet",270 "country_codes": [271 "US"272 ],273 "initial_products": [274 "transactions"275 ],276 "language": "en",277 "redirect_uri": null,278 "webhook": "https://webhook.site/dc9c138f-75de-4db1-883a-a4add4b7eb7e"279 },280 "request_id": "Pxpgzy0Wjvn99mY"281}
Was this helpful?
Webhooks
ITEM_ADD_RESULT
Fired when a user successfully adds a Plaid Item during a Link session when using Hosted Link or Multi-Item Link sessions. Contains the public token for the Item.
webhook_type
LINK
webhook_code
ITEM_ADD_RESULT
link_session_id
link_token
public_token
environment
sandbox
, production
1{2 "webhook_type": "LINK",3 "webhook_code": "ITEM_ADD_RESULT",4 "link_session_id": "356dbb28-7f98-44d1-8e6d-0cec580f3171",5 "link_token": "link-sandbox-af1a0311-da53-4636-b754-dd15cc058176",6 "public_token": "public-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d",7 "environment": "sandbox"8}
Was this helpful?
EVENTS
This webhook contains a summary of the events from a Link session and will be fired after the user finishes going through Link. If the user abandons the Link flow (i.e., closes the hosted link webpage or leaves Link open for too long without taking any action), the webhook will be fired 5-15 minutes after the last user interaction. A single Link session may occasionally generate multiple EVENTS
webhooks. If this occurs, the new webhook will contain all previous events for the session, as well as new events that occurred since the previous EVENTS
webhook was sent. If this occurs, events can be grouped using the link_session_id
field and, if necessary, de-duplicated using the event_id
field.
By default, the EVENTS
webhook is enabled only for clients that are enabled for Hosted Link. If you would like to receive this webhook and are not using Hosted Link, contact your Account Manager.
webhook_type
LINK
webhook_code
EVENTS
events
event_name
event_id
event_metadata
error_code
ERROR
, EXIT
.error_message
ERROR
, EXIT
.error_type
ERROR
, EXIT
.exit_status
EXIT
.institution_id
institution_name
institution_search _query
SEARCH_INSTITUTION
.request_id
mfa_type
SUBMIT_MFA
and TRANSITION_VIEW
when viewname is MFA
.view_name
TRANSITION_VIEW
.selection
phoneotp
or password
; if selection is used to describe the selected Auth Type Select flow, then possible values are flow_type_manual
or flow_type_instant
. Emitted by: MATCHED_SELECT_VERIFY_METHOD
and SELECT_AUTH_TYPE
.brand_name
match_reason
returning_user
or routing_number
. Emitted by: MATCHED_SELECT_INSTITUTION
.routing_number
SUBMIT_ROUTING_NUMBER
.account_number_mask
account_number_mask
is empty. Emitted by SUBMIT_ACCOUNT_NUMBER
.link_session_id
link_token
1{2 "environment": "sandbox",3 "link_session_id": "1daca4d5-9a0d-4e85-a2e9-1e905ecaa32e",4 "link_token": "link-sandbox-79e723b0-0e04-4248-8a33-15ceb6828a45",5 "webhook_code": "EVENTS",6 "webhook_type": "LINK",7 "events": [8 {9 "event_id": "9469937a-6fac-40be-9322-f86e8c0b94ed",10 "event_metadata": {11 "request_id": "ClqZyuhovgkaQ3j"12 },13 "event_name": "TRANSITION_VIEW",14 "timestamp": "2024-05-21T00:17:54Z"15 },16 {17 "event_id": "4b2390cf-33a2-4078-b933-62468b9e53a5",18 "event_metadata": {19 "error_code": "INVALID_CREDENTIALS",20 "error_message": "the provided credentials were not correct",21 "error_type": "ITEM_ERROR",22 "institution_id": "ins_20",23 "institution_name": "Citizens Bank",24 "request_id": "ttK0NtGKaVAlbCR"25 },26 "event_name": "ERROR",27 "timestamp": "2024-05-21T00:18:09Z"28 },29 {30 "event_id": "45f76afe-f2aa-495c-a326-f37e043a1ccd",31 "event_metadata": {32 "request_id": "WRJqqeh8Hxife05"33 },34 "event_name": "TRANSITION_VIEW",35 "timestamp": "2024-05-21T00:17:56Z"36 },37 {38 "event_id": "978b772c-f2cc-404f-9449-2113e4671c4f",39 "event_metadata": {40 "error_code": "INVALID_CREDENTIALS",41 "error_message": "the provided credentials were not correct",42 "error_type": "ITEM_ERROR",43 "exit_status": "requires_credentials",44 "institution_id": "ins_20",45 "institution_name": "Citizens Bank",46 "request_id": "u1HcAeiCKtz3qmm"47 },48 "event_name": "EXIT",49 "timestamp": "2024-05-21T00:18:13Z"50 },51 {52 "event_id": "a873db76-aa4e-4a00-9d60-7ae08aa8e63f",53 "event_metadata": {54 "institution_id": "ins_20",55 "institution_name": "Citizens Bank",56 "request_id": "ttK0NtGKaVAlbCR"57 },58 "event_name": "TRANSITION_VIEW",59 "timestamp": "2024-05-21T00:18:09Z"60 },61 {62 "event_id": "ca85566d-5f32-4716-909f-82f3a0b6160b",63 "event_metadata": {64 "institution_id": "ins_20",65 "institution_name": "Citizens Bank",66 "request_id": "XRvev3cP9wYUFz5"67 },68 "event_name": "SUBMIT_CREDENTIALS",69 "timestamp": "2024-05-21T00:18:07Z"70 },71 {72 "event_id": "09220752-6b83-407e-baf0-f6228df16ea0",73 "event_metadata": {74 "institution_id": "ins_20",75 "institution_name": "Citizens Bank",76 "request_id": "WRJqqeh8Hxife05"77 },78 "event_name": "SELECT_INSTITUTION",79 "timestamp": "2024-05-21T00:18:01Z"80 },81 {82 "event_id": "1c75d2ee-19c1-4d1b-8600-7d06cecbb270",83 "event_metadata": {84 "institution_id": "ins_20",85 "institution_name": "Citizens Bank",86 "request_id": "5vc1IyBHfLkIVFx"87 },88 "event_name": "TRANSITION_VIEW",89 "timestamp": "2024-05-21T00:18:12Z"90 },91 {92 "event_id": "1c9c9059-c065-4362-836a-d9afb91a6125",93 "event_metadata": {94 "request_id": "MlFW5NSWtCs1KLI"95 },96 "event_name": "TRANSITION_VIEW",97 "timestamp": "2024-05-21T00:17:50Z"98 },99 {100 "event_id": "4f381b3f-172b-4bca-9804-c230f8d36a3b",101 "event_metadata": {102 "institution_id": "ins_20",103 "institution_name": "Citizens Bank",104 "request_id": "XRvev3cP9wYUFz5"105 },106 "event_name": "TRANSITION_VIEW",107 "timestamp": "2024-05-21T00:18:02Z"108 },109 {110 "event_id": "dd9d4747-d4da-4c11-88d6-b5a0e96f1886",111 "event_metadata": {112 "request_id": "ClqZyuhovgkaQ3j"113 },114 "event_name": "SKIP_SUBMIT_PHONE",115 "timestamp": "2024-05-21T00:17:55Z"116 }117 ]118}
Was this helpful?
SESSION_FINISHED
Contains the state of a completed Link session, along with the public token(s) if available.
By default, the SESSION_FINISHED
webhook is enabled only for clients that are enabled for Hosted Link, or in sessions that are enabled for Multi-Item Link. If you would like to receive this webhook and are not using Hosted Link or Multi-Item Link, contact your Account Manager.
webhook_type
LINK
webhook_code
SESSION_FINISHED
status
link_session_id
link_token
public_token
public_tokens
instead.public_tokens
environment
sandbox
, production
1{2 "webhook_type": "LINK",3 "webhook_code": "SESSION_FINISHED",4 "status": "SUCCESS",5 "link_session_id": "356dbb28-7f98-44d1-8e6d-0cec580f3171",6 "link_token": "link-sandbox-af1a0311-da53-4636-b754-dd15cc058176",7 "public_tokens": [8 "public-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d"9 ],10 "environment": "sandbox"11}