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/createCreate a token for initializing a Link session
/link/token/getGet the public token and other details about a completed Link session
See also
/item/public_token/exchangeExchange a public token for an access token
/sandbox/public_token/createCreate a public token without the Link flow (Sandbox only)
/sandbox/item/reset_loginForce an Item into an error state (Sandbox only)
Webhooks
ITEM_ADD_RESULTAn Item was added during a Link session
EVENTSEvents were received from a Hosted Link session
SESSION_FINISHEDThe 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.

link/token/create
Request fields
client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
client_name
requiredstring
The name of your application, as it should be displayed in Link. Maximum length of 30 characters. If a value longer than 30 characters is provided, Link will display "This Application" instead.

Min length: 1
language
requiredstring
The language that Link should be displayed in. When initializing with Identity Verification, this field is not used; for more details, see Identity Verification supported languages.
Supported languages are:
  • Danish ('da')
  • Dutch ('nl')
  • English ('en')
  • Estonian ('et')
  • French ('fr')
  • German ('de')
  • Hindi ('hi')
  • Italian ('it')
  • Latvian ('lv')
  • Lithuanian ('lt')
  • Norwegian ('no')
  • Polish ('pl')
  • Portuguese ('pt')
  • Romanian ('ro')
  • Spanish ('es')
  • Swedish ('sv')
  • Vietnamese ('vi')

When using a Link customization, the language configured here must match the setting in the customization, or the customization will not be applied.

Min length: 1
country_codes
required[string]
Specify an array of Plaid-supported country codes using the ISO-3166-1 alpha-2 country code standard. Institutions from all listed countries will be shown. For a complete mapping of supported products by country, see https://plaid.com/global/.
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'].

Min items: 1
Possible values: US, GB, ES, NL, FR, IE, CA, DE, IT, PL, DK, NO, SE, EE, LT, LV, PT, BE
user
requiredobject
An object specifying information about the end user who will be linking their account.
client_user_id
requiredstring
A unique ID representing the end user. Typically this will be a user ID number from your application. Personally identifiable information, such as an email address or phone number, should not be used in the client_user_id. It is currently used as a means of searching logs for the given user in the Plaid Dashboard.

Min length: 1
legal_name
string
The user's full legal name, used for micro-deposit based verification flows. For a small number of customers on legacy flows, providing this field is required to enable micro-deposit-based flows. For all other customers, this field is optional. Providing the user's name in this field when using micro-deposit-based verification will streamline the end user experience, as the user will not be prompted to enter their name during the Link flow; Plaid will use the provided legal name instead.
name
object
The user's full name. Optional if using the Identity Verification product; if not using Identity Verification, this field is not allowed. Users will not be asked for their name when this field is provided.
given_name
requiredstring
A string with at least one non-whitespace character, with a max length of 100 characters.
family_name
requiredstring
A string with at least one non-whitespace character, with a max length of 100 characters.
phone_number
string
The user's phone number in E.164 format. If supplied, will be used when applicable to prefill phone number fields in Link for the returning user flow and the Identity Verification flow.
email_address
string
The user's email address. Can be used to prefill Link fields when used with Identity Verification.
date_of_birth
string
To be provided in the format "yyyy-mm-dd". Can be used to prefill Link fields when used with Identity Verification.

Format: date
address
object
The user's address. Used only for Identity Verification. If provided, the user will not be shown fields to enter their address in the Identity Verification flow. May be omitted, but if not omitted, all fields marked as required must be provided.
street
string
The primary street portion of an address. If an address is provided, this field will always be filled. A string with at least one non-whitespace alphabetical character, with a max length of 80 characters.
street2
string
Extra street information, like an apartment or suite number. If provided, a string with at least one non-whitespace character, with a max length of 50 characters.
city
string
City from the end user's address. A string with at least one non-whitespace alphabetical character, with a max length of 100 characters."
region
string
An ISO 3166-2 subdivision code. Related terms would be "state", "province", "prefecture", "zone", "subdivision", etc.
postal_code
string
The postal code for the associated address. Between 2 and 10 alphanumeric characters. For US-based addresses this must be 5 numeric digits.
country
requiredstring
Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.
id_number
object
The user's ID number. Used only for Identity Verification. If provided, the user will not be shown fields to enter their ID number in the Identity Verification flow. May be omitted, but if not omitted, all fields marked as required must be provided.
value
requiredstring
Value of identity document value typed in by user. Alpha-numeric, with all formatting characters stripped. For specific format requirements by ID type, see Hybrid Input Validation.
type
requiredstring
A globally unique and human readable ID type, specific to the country and document category. For more context on this field, see Hybrid Input Validation.

Possible values: ar_dni, au_drivers_license, au_passport, br_cpf, ca_sin, cl_run, cn_resident_card, co_nit, dk_cpr, eg_national_id, es_dni, es_nie, hk_hkid, in_pan, it_cf, jo_civil_id, jp_my_number, ke_huduma_namba, kw_civil_id, mx_curp, mx_rfc, my_nric, ng_nin, nz_drivers_license, om_civil_id, ph_psn, pl_pesel, ro_cnp, sa_national_id, se_pin, sg_nric, tr_tc_kimlik, us_ssn, us_ssn_last_4, za_smart_id
products
[string]
List of Plaid product(s) you wish to use. If launching Link in update mode, should be omitted (unless you are using update mode to add Income or Assets to an Item); required otherwise.
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 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.

Possible values: 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_network_insights, cra_cashflow_insights, layer
required_if_supported_products
[string]
List of Plaid product(s) you wish to use only if the institution and account(s) selected by the user support the product. Institutions that do not support these products will still be shown in Link. The products will only be extracted and billed if the user selects an institution and account type that supports them.
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.

Possible values: auth, identity, investments, liabilities, transactions, signal, statements
optional_products
[string]
List of Plaid product(s) that will enhance the consumer's use case, but that your app can function without. Plaid will attempt to fetch data for these products on a best-effort basis, and failure to support these products will not affect Item creation.
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.

Possible values: auth, identity, investments, liabilities, signal, statements, transactions
additional_consented_products
[string]
List of additional Plaid product(s) you wish to collect consent for to support your use case. These products will not be billed until you start using them by calling the relevant endpoints.
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.
If you include signal in additional_consented_products, you will need to call /signal/prepare before calling /signal/evaluate for the first time on an Item in order to get the most accurate results. For more details, see Using /signal/prepare.

Possible values: auth, balance_plus, identity, investments, liabilities, transactions, signal
webhook
string
The destination URL to which any webhooks should be sent. Note that webhooks for Payment Initiation (e-wallet transactions only), Transfer, Bank Transfer (including Auth micro-deposit notification webhooks), Monitor, Identity Verification, and Link Events are configured via the Dashboard instead. In update mode, this field will not have an effect; to update the webhook receiver endpoint for an existing Item, use /item/webhook/update instead.
access_token
string
The 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.

Min length: 1
link_customization_name
string
The name of the Link customization from the Plaid Dashboard to be applied to Link. If not specified, the 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
string
A URI indicating the destination where a user should be forwarded after completing the Link flow; used to support OAuth authentication flows when launching Link in the browser or another app. The 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
string
The name of your app's Android package. Required if using the 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
object
A map containing data used to highlight institutions in Link.
routing_number
string
The routing number of the bank to highlight in Link. Note: in rare cases, a single routing number can be associated with multiple institutions, e.g. due to a brokerage using another institution to manage ACH on its sweep accounts. If this happens, the bank will not be highlighted in Link even if the routing number is provided.
account_filters
object
By default, Link will provide limited account filtering: it will only display Institutions that are compatible with all products supplied in the products parameter of /link/token/create, and, if auth is specified in the products array, will also filter out accounts other than checking, savings, and cash management 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
object
A filter to apply to depository-type accounts
account_subtypes
required[string]
An array of account subtypes to display in Link. If not specified, all account subtypes will be shown. For a full list of valid types and subtypes, see the Account schema.

Possible values: checking, savings, hsa, cd, money market, paypal, prepaid, cash management, ebt, all
credit
object
A filter to apply to credit-type accounts
account_subtypes
required[string]
An array of account subtypes to display in Link. If not specified, all account subtypes will be shown. For a full list of valid types and subtypes, see the Account schema.

Possible values: credit card, paypal, all
loan
object
A filter to apply to loan-type accounts
account_subtypes
required[string]
An array of account subtypes to display in Link. If not specified, all account subtypes will be shown. For a full list of valid types and subtypes, see the Account schema.

Possible values: auto, business, commercial, construction, consumer, home equity, loan, mortgage, line of credit, student, other, all
investment
object
A filter to apply to investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier).
account_subtypes
required[string]
An array of account subtypes to display in Link. If not specified, all account subtypes will be shown. For a full list of valid types and subtypes, see the Account schema.

Possible values: 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
object
A filter to apply to other-type accounts
account_subtypes
required[string]
An array of account subtypes to display in Link. If not specified, all account subtypes will be shown. For a full list of valid types and subtypes, see the Account schema.

Possible values: other, all
eu_config
object
Configuration parameters for EU flows
headless
boolean
If true, open Link without an initial UI. Defaults to false.
institution_id
string
Used for certain Europe-only configurations, as well as certain legacy use cases in other regions.
payment_initiation
object
Specifies options for initializing Link for use with the Payment Initiation (Europe) product. This field is required if payment_initiation is included in the products array. Either payment_id or consent_id must be provided.
payment_id
string
The payment_id provided by the /payment_initiation/payment/create endpoint.
consent_id
string
The consent_id provided by the /payment_initiation/consent/create endpoint.
income_verification
object
Specifies options for initializing Link for use with the Income product. This field is required if income_verification is included in the products array.
asset_report_id
string
The 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
[string]
An array of access tokens corresponding to Items that a user has previously connected with. Data from these institutions will be cross-referenced with document data received during the Document Income flow to help verify that the uploaded documents are accurate. If the 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
[string]
The types of source income data that users will be permitted to share. Options include bank and payroll. Currently you can only specify one of these options.

Possible values: bank, payroll
bank_income
object
Specifies options for initializing Link for use with Bank Income. This field is required if income_verification is included in the products array and bank is specified in income_source_types.
days_requested
requiredinteger
The number of days of data to request for the Bank Income product

Minimum: 1
Maximum: 731
enable_multiple_items
deprecatedboolean
Whether to enable multiple Items to be added in the Link session. This setting is deprecated and has been replaced by the more general enable_multi_item_link setting, which supports all products.

Default: false
payroll_income
object
Specifies options for initializing Link for use with Payroll Income (including Document Income). Further customization options for Document Income, such as customizing which document types may be uploaded, are also available via the Link Customization pane in the Dashboard. (Requires Production enablement.)
flow_types
[string]
The types of payroll income verification to enable for the Link session. If none are specified, then users will see both document and digital payroll income.

Possible values: payroll_digital_income, payroll_document_income
is_update_mode
boolean
An identifier to indicate whether the income verification Link token will be used for update mode. This field is only relevant for participants in the Payroll Income Refresh beta.

Default: false
item_id_to_update
string
Uniquely identify a payroll income Item to update with. This field is only relevant for participants in the Payroll Income Refresh beta.
parsing_config
[string]
The types of analysis to enable for document uploads. If this field is not provided, then docs will undergo OCR parsing only.

Possible values: ocr, risk_signals
stated_income_sources
[object]
A list of user stated income sources
employer
string
The employer corresponding to an income source specified by the user
category
string
The income category for a specified income source

Possible values: OTHER, SALARY, UNEMPLOYMENT, CASH, GIG_ECONOMY, RENTAL, CHILD_SUPPORT, MILITARY, RETIREMENT, LONG_TERM_DISABILITY, BANK_INTEREST
pay_per_cycle
number
The income amount paid per cycle for a specified income source

Format: double
pay_annual
number
The income amount paid annually for a specified income source

Format: double
pay_type
string
The pay type - GROSS, NET, or UNKNOWN for a specified income source

Possible values: UNKNOWN, GROSS, NET
pay_frequency
string
The pay frequency of a specified income source

Possible values: UNKNOWN, WEEKLY, BIWEEKLY, SEMI_MONTHLY, MONTHLY
cra_options
object
Specifies options for initializing Link for use with Plaid Check products
days_requested
requiredinteger
The number of days of history to include in Plaid Check products. Default value is 365; maximum is 730; minimum is 180. If a value lower than 180 is provided, a minimum of 180 days of history will be requested.

Maximum: 730
days_required
integer
The minimum number of days of data required for the report to be successfully generated.

Maximum: 730
partner_insights
object
Specifies options for initializing Link for use with the Credit Partner Insights product.
prism_products
[string]
The specific Prism products to return. If none are passed in, then all products will be returned.

Possible values: insights, scores
prism_versions
object
The versions of Prism products to evaluate
firstdetect
string
The version of Prism FirstDetect. If not specified, will default to v3.

Possible values: 3, null
cashscore
string
The version of Prism CashScore. If not specified, will default to v3.

Possible values: 3_lite, 3, null
insights
string
The version of Prism Insights. If not specified, will default to v3.

Possible values: 3, null
base_report
object
Specifies options for initializing Link for use with the Base Report product.
client_report_id
string
Client-generated identifier, which can be used by lenders to track loan applications.
cashflow_insights
object
Specifies options for initializing Link for use with the Cashflow Insights product.
attributes_version
string
The versions of cashflow attributes

Possible values: v1.0
consumer_report_permissible_purpose
string
Describes the reason you are generating a Consumer Report for this user. This parameter is required if you want to generate a Consumer Report for the user automatically after the Link session. If you omit this parameter during Link token creation, you can later call the /cra/check_report/create endpoint to generate a report.
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.

Possible values: 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
object
Specifies options for initializing Link for use with the Auth product. This field can be used to enable or disable extended Auth flows for the resulting Link session. Omitting any field will result in a default that can be configured by your account manager. The default behavior described in the documentation is the default behavior that will apply if you have not requested your account manager to apply a different default.
auth_type_select_enabled
boolean
Specifies whether Auth Type Select is enabled for the Link session, allowing the end user to choose between linking via a credentials-based flow (i.e. Instant Auth, Instant Match, Automated Micro-deposits) or a manual flow that does not require login (all other Auth flows) prior to selecting their financial institution. Default behavior is false.
automated_microdeposits_enabled
boolean
Specifies whether the Link session is enabled for the Automated Micro-deposits flow. Default behavior is false.
instant_match_enabled
boolean
Specifies whether the Link session is enabled for the Instant Match flow. Instant Match is enabled by default. Instant Match can be disabled by setting this field to false.
same_day_microdeposits_enabled
boolean
Specifies whether the Link session is enabled for the Same Day Micro-deposits flow. Default behavior is false.
instant_microdeposits_enabled
boolean
Specifies whether the Link session is enabled for the Instant Micro-deposits flow. Default behavior for Plaid teams created after November 2023 is false; default behavior for Plaid teams created before that date is true.
reroute_to_credentials
string
Specifies what type of Reroute to Credentials pane should be used in the Link session for the Same Day Micro-deposits flow. Default behavior is OPTIONAL.

Possible values: OFF, OPTIONAL, FORCED
database_match_enabled
boolean
Specifies whether the Link session is enabled for the Database Match flow. Default behavior is false.
database_insights_enabled
boolean
Specifies whether the Link session is enabled for the Database Insights flow. Database Insights is currently in closed beta; for access, contact your Account Manager. Default behavior is false.
flow_type
deprecatedstring
This field has been deprecated in favor of auth_type_select_enabled.

Possible values: FLEXIBLE_AUTH
sms_microdeposits_verification_enabled
boolean
Specifies whether the Link session is enabled for SMS micro-deposits verification. Default behavior is true.
transfer
object
Specifies options for initializing Link for use with the Transfer product.
intent_id
string
The id returned by the /transfer/intent/create endpoint.
authorization_id
string
The 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
object
Specifies options for initializing Link for update mode.
account_selection_enabled
boolean
If 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.

Default: false
reauthorization_enabled
boolean
By default, Plaid will enable the reauthorization flow during update mode for an Item enabled for Data Transparency Messaging if the Item expires within six months. During a reauthorization flow, an end user will review Plaid's end user privacy policy, use case and data scope consents, and account access consents; they may also be required to log in to their financial institution's OAuth flow. After the end user successfully completes the reauthorization flow, the Item's expiration date will be extended to 12 months from the time that the reauthorization took place. This field allows you to optionally override the default reauthorization scheduling logic to either forcibly enable or disable the reauthorization flow for a given update mode session. This field does not impact the flow for Items at institutions in the EU or UK.
user
boolean
If true, a user_token must also be provided, and Link will open in update mode for the given user.

Default: false
item_ids
[string]
An array of item_ids 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
object
Specifies option for initializing Link for use with the Identity Verification product.
template_id
requiredstring
ID of the associated Identity Verification template.
gave_consent
boolean
A flag specifying whether the end user has already agreed to a privacy policy specifying that their data will be shared with Plaid for verification purposes.
If gave_consent is set to true, the accept_tos step will be marked as skipped and the end user's session will start at the next step requirement.

Default: false
statements
object
Specifies options for initializing Link for use with the Statements product. This field is required for the statements product.
start_date
requiredstring
The start date for statements, in ISO 8601 "YYYY-MM-DD" format, e.g. "2020-10-30".

Format: date
end_date
requiredstring
The end date for statements, in ISO 8601 "YYYY-MM-DD" format, e.g. "2020-10-30". You can request up to two years of data.

Format: date
user_token
string
A user token generated using /user/create. Any Item created during the Link session will be associated with the user.
investments
object
Configuration parameters for the Investments product
allow_unverified_crypto_wallets
boolean
If true, allow self-custody crypto wallets to be added without requiring signature verification. Defaults to false.
allow_manual_entry
boolean
If true, allow users to manually enter Investments account and holdings information. Defaults to false.
investments_auth
object
Configuration parameters for the Investments Move product
manual_entry_enabled
boolean
If true, show institutions that use the manual entry fallback flow.

Default: false
masked_number_match_enabled
boolean
If true, show institutions that use the masked number match fallback flow.

Default: false
stated_account_number_enabled
boolean
If true, show institutions that use the stated account number fallback flow.

Default: false
hosted_link
object
Configuration parameters for Hosted Link. To enable the session for Hosted Link, send this object in the request. It can be empty.
delivery_method
string
How Plaid should deliver the Plaid Link session to the customer. Only available to customers enabled for Link Delivery (beta). To request Link Delivery access, contact your account manager. 'sms' will deliver via SMS. Must pass 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.

Possible values: sms, email
completion_redirect_uri
string
URI that Hosted Link will redirect to upon completion of the Link flow. This will only occur in Hosted Link sessions, not in other implementation methods.
url_lifetime_seconds
integer
How many seconds the link will be valid for. Must be positive. Cannot be longer than 21 days. The default lifetime is 7 days for links delivered by email, 1 day for links delivered via SMS, and 30 minutes for links not sent via Plaid Link delivery. This parameter will override the value of all three link types.
is_mobile_app
boolean
This indicates whether the client is opening hosted Link in a mobile app in an out of process web view (OOPWV) (i.e., an AsWebAuthenticationSession / SFSafariViewController or Android Custom Tab).

Default: false
transactions
object
Configuration parameters for the Transactions product
days_requested
integer
The maximum number of days of transaction history to request for the Transactions product. The more transaction history is requested, the longer the historical update poll will take. The default value is 90 days. If a value under 30 is provided, a minimum of 30 days of history will be requested. Once Transactions has been added to an Item, this value cannot be updated.
Customers using Recurring Transactions should request at least 180 days of history for optimal results.

Minimum: 1
Maximum: 730
Default: 90
identity
object
Identity object used to specify document upload
is_document_upload
boolean
Used to specify whether the Link session is Identity Document Upload
account_ids
[string]
An array of account_ids. Currently can only contain one account_id. Must be populated if using Document Upload.
parsing_configs
[string]
An array of parsing configurations. Valid parsing configurations are ocr and risk_signals. If parsing configurations are omitted, defaults to ocr

Possible values: ocr, risk_signals
enable_multi_item_link
boolean
If true, enable linking multiple items in the same Link session. Defaults to false.

1const request: LinkTokenCreateRequest = {
2  loading_sample: true
3};
4try {
5  const response = await plaidClient.linkTokenCreate(request);
6  const linkToken = response.data.link_token;
7} catch (error) {
8  // handle error
9}
link/token/create

Response fields and example

link_token
string
A 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
string
The expiration date for the link_token, in ISO 8601 format. By default, a link_token created to generate a public_token that will be exchanged for a new access_token expires after 4 hours, and 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. If using Hosted Link, the link_token will expire at the same time as the Hosted Link URL, and you can customize the duration using the hosted_link.url_lifetime_seconds option in the request. If using Link Delivery (beta), the link_token will expire by default after 24 hours if sent via SMS and after 7 days if sent via email.

Format: date-time
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
hosted_link_url
string
A URL of a Plaid-hosted Link flow that will use the Link token returned by this request. Only present if the session is enabled for Hosted Link. To enable the session for Hosted Link, send a hosted_link object in the request.
1{
2  "link_token": "link-sandbox-af1a0311-da53-4636-b754-dd15cc058176",
3  "expiration": "2020-03-27T12:56:34Z",
4  "request_id": "XQVgFigpGHXkb0b"
5}

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

link/token/get
Request fields
client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
link_token
requiredstring
A link_token from a previous invocation of /link/token/create
Select group for content switcher
1const request: LinkTokenGetRequest = {
2  link_token: linkToken,
3};
4try {
5  const response = await plaidClient.linkTokenGet(request);
6} catch (error) {
7  // handle error
8}
link/token/get

Response fields and example

link_token
string
A 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
nullablestring
The creation timestamp for the link_token, in ISO 8601 format.

Format: date-time
expiration
nullablestring
The expiration timestamp for the link_token, in ISO 8601 format.

Format: date-time
link_sessions
[object]
Information about Link sessions created using this link_token. Session data will be provided for up to six hours after the session has ended.
link_session_id
string
The unique ID for the link session.
started_at
string
The timestamp at which the link session was first started, in ISO 8601 format.

Format: date-time
finished_at
nullablestring
The timestamp at which the link session was finished, if available, in ISO 8601 format.

Format: date-time
on_success
deprecatednullableobject
An object representing an onSuccess callback from Link. This object has been deprecated in favor of the newer results.item_add_result, which can support multiple public tokens in a single Link session.
public_token
string
Displayed once a user has successfully linked their Item.
metadata
nullableobject
Displayed once a user has successfully linked their Item.
institution
nullableobject
An institution object. If the Item was created via Same-Day or Instant micro-deposit verification, will be null.
name
string
The full institution name, such as 'Wells Fargo'
institution_id
string
The Plaid institution identifier
accounts
[object]
A list of accounts attached to the connected Item. If Account Select is enabled via the developer dashboard, accounts will only include selected accounts.
id
string
The Plaid account_id
name
string
The official account name
mask
nullablestring
The last 2-4 alphanumeric characters of an account's official account number. Note that the mask may be non-unique between an Item's accounts. It may also not match the mask that the bank displays to the user.
type
string
The account type. See the Account schema for a full list of possible values
subtype
string
The account subtype. See the Account schema for a full list of possible values
verification_status
nullablestring
Indicates an Item's micro-deposit-based verification or database verification status. Possible values are:
pending_automatic_verification: The Item is pending automatic verification
pending_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 verified
manually_verified: The Item has successfully been manually verified
verification_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
deprecatednullablestring
If micro-deposit verification was being used, indicates the user's selection when asked if the account being verified is a business or personal account. This field is deprecated as Plaid no longer collects this information during the micro-deposit flow. To see whether an account is business or personal, use the holder_category field instead.
link_session_id
string
A unique identifier associated with a user's actions and events through the Link flow. Include this identifier when opening a support ticket for faster turnaround.
transfer_status
nullablestring
The status of a transfer. Returned only when Transfer UI is implemented.
  • COMPLETE – The transfer was completed.
  • INCOMPLETE – The transfer could not be completed. For help, see Troubleshooting transfers.


Possible values: COMPLETE, INCOMPLETE, null
on_exit
deprecatednullableobject
An object representing an onExit callback from Link. This field has been deprecated in favor of exit, for improved naming consistency.
error
nullableobject
Errors are identified by 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
string
A broad categorization of the error. Safe for programmatic use.

Possible values: 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
string
The particular error code. Safe for programmatic use.
error_code_reason
nullablestring
The specific reason for the error code. Currently, reasons are only supported OAuth-based item errors; 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_USER_REVOKED: The user’s OAuth connection to this institution is invalid because the user revoked their connection.
error_message
string
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.
display_message
nullablestring
A user-friendly representation of the error code. null if the error is not related to user action.
This may change over time and is not safe for programmatic use.
request_id
string
A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks.
causes
array
In this product, a request can pertain to more than one Item. If an error is returned for such a request, 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
nullableinteger
The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook.
documentation_url
string
The URL of a Plaid documentation page with more information about the error
suggested_action
nullablestring
Suggested steps for resolving the error
metadata
nullableobject
Displayed if a user exits Link without successfully linking an Item.
institution
nullableobject
An institution object. If the Item was created via Same-Day or Instant micro-deposit verification, will be null.
name
string
The full institution name, such as Wells Fargo
institution_id
string
The Plaid institution identifier
status
string
The point at which the user exited the Link flow. One of the following values.
requires_questions
User prompted to answer security questions
requires_selections
User prompted to answer multiple choice question(s)
requires_code
User prompted to provide a one-time passcode
choose_device
User prompted to select a device on which to receive a one-time passcode
requires_credentials
User prompted to provide credentials for the selected financial institution or has not yet selected a financial institution
requires_account_selection
User prompted to select one or more financial accounts to share
requires_oauth
User prompted to enter an OAuth flow
institution_not_found
User exited the Link flow after unsuccessfully (no results returned) searching for a financial institution
institution_not_supported
User exited the Link flow after discovering their selected institution is no longer supported by Plaid
link_session_id
string
A unique identifier associated with a user's actions and events through the Link flow. Include this identifier when opening a support ticket for faster turnaround.
request_id
string
The request ID for the last request made by Link. This can be shared with Plaid Support to expedite investigation.
exit
nullableobject
An object representing an onExit callback from Link.
error
nullableobject
Errors are identified by 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
string
A broad categorization of the error. Safe for programmatic use.

Possible values: 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
string
The particular error code. Safe for programmatic use.
error_code_reason
nullablestring
The specific reason for the error code. Currently, reasons are only supported OAuth-based item errors; 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_USER_REVOKED: The user’s OAuth connection to this institution is invalid because the user revoked their connection.
error_message
string
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.
display_message
nullablestring
A user-friendly representation of the error code. null if the error is not related to user action.
This may change over time and is not safe for programmatic use.
request_id
string
A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks.
causes
array
In this product, a request can pertain to more than one Item. If an error is returned for such a request, 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
nullableinteger
The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook.
documentation_url
string
The URL of a Plaid documentation page with more information about the error
suggested_action
nullablestring
Suggested steps for resolving the error
metadata
nullableobject
Displayed if a user exits Link without successfully linking an Item.
institution
nullableobject
An institution object. If the Item was created via Same-Day or Instant micro-deposit verification, will be null.
name
string
The full institution name, such as Wells Fargo
institution_id
string
The Plaid institution identifier
status
string
The point at which the user exited the Link flow. One of the following values.
requires_questions
User prompted to answer security questions
requires_selections
User prompted to answer multiple choice question(s)
requires_code
User prompted to provide a one-time passcode
choose_device
User prompted to select a device on which to receive a one-time passcode
requires_credentials
User prompted to provide credentials for the selected financial institution or has not yet selected a financial institution
requires_account_selection
User prompted to select one or more financial accounts to share
requires_oauth
User prompted to enter an OAuth flow
institution_not_found
User exited the Link flow after unsuccessfully (no results returned) searching for a financial institution
institution_not_supported
User exited the Link flow after discovering their selected institution is no longer supported by Plaid
link_session_id
string
A unique identifier associated with a user's actions and events through the Link flow. Include this identifier when opening a support ticket for faster turnaround.
request_id
string
The request ID for the last request made by Link. This can be shared with Plaid Support to expedite investigation.
events
[object]
List of customer-related Link events
event_name
string
Event name
timestamp
string
Timestamp in ISO 8601 format.
event_id
string
UUID that can be used to deduplicate events
event_metadata
object
Metadata about an event that occurred while the user was going through Link
error_code
string
The error code that the user encountered. Emitted by ERROR, EXIT.
error_message
string
The error message that the user encountered. Emitted by: ERROR, EXIT.
error_type
string
The error type that the user encountered. Emitted by: ERROR, EXIT.
exit_status
string
The status key indicates the point at which the user exited the Link flow. Emitted by: EXIT.
institution_id
string
The ID of the selected institution. Emitted by: all events.
institution_name
string
The name of the selected institution. Emitted by: all events.
institution_search_query
string
The query used to search for institutions. Emitted by: SEARCH_INSTITUTION.
request_id
string
The request ID for the last request made by Link. This can be shared with Plaid Support to expedite investigation. Emitted by: all events.
mfa_type
string
If set, the user has encountered one of the following MFA types: code, device, questions, selections. Emitted by: SUBMIT_MFA and TRANSITION_VIEW when view_name is MFA.
view_name
string
The name of the view that is being transitioned to. Emitted by: TRANSITION_VIEW.
selection
string
Either the verification method for a matched institution selected by the user or the Auth Type Select flow type selected by the user. If selection is used to describe selected verification method, then possible values are 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
string
The name of the selected brand.
match_reason
string
The reason this institution was matched, which will be either returning_user or routing_number. Emitted by: MATCHED_SELECT_INSTITUTION.
routing_number
string
The routing number submitted by user at the micro-deposits routing number pane. Emitted by SUBMIT_ROUTING_NUMBER.
account_number_mask
string
The account number mask extracted from the user-provided account number. If the user-inputted account number is four digits long, account_number_mask is empty. Emitted by SUBMIT_ACCOUNT_NUMBER.
results
nullableobject
The set of results for a Link session.
item_add_results
[object]
The set of Item adds for the Link session.
public_token
string
Returned once a user has successfully linked their Item.
accounts
[object]
A list of accounts attached to the connected Item. If Account Select is enabled via the developer dashboard, accounts will only include selected accounts.
id
string
The Plaid account_id
name
string
The official account name
mask
nullablestring
The last 2-4 alphanumeric characters of an account's official account number. Note that the mask may be non-unique between an Item's accounts. It may also not match the mask that the bank displays to the user.
type
string
The account type. See the Account schema for a full list of possible values
subtype
string
The account subtype. See the Account schema for a full list of possible values
verification_status
nullablestring
Indicates an Item's micro-deposit-based verification or database verification status. Possible values are:
pending_automatic_verification: The Item is pending automatic verification
pending_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 verified
manually_verified: The Item has successfully been manually verified
verification_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
deprecatednullablestring
If micro-deposit verification was being used, indicates the user's selection when asked if the account being verified is a business or personal account. This field is deprecated as Plaid no longer collects this information during the micro-deposit flow. To see whether an account is business or personal, use the holder_category field instead.
institution
nullableobject
An institution object. If the Item was created via Same-Day or Instant micro-deposit verification, will be null.
name
string
The full institution name, such as 'Wells Fargo'
institution_id
string
The Plaid institution identifier
cra_item_add_results
[object]
The set of Plaid Check Item adds for the Link session.
item_id
string
The Plaid Check Item ID. The 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
[object]
A list of accounts attached to the connected Item. If Account Select is enabled via the developer dashboard, accounts will only include selected accounts.
id
string
The Plaid account_id
name
string
The official account name
mask
nullablestring
The last 2-4 alphanumeric characters of an account's official account number. Note that the mask may be non-unique between an Item's accounts. It may also not match the mask that the bank displays to the user.
type
string
The account type. See the Account schema for a full list of possible values
subtype
string
The account subtype. See the Account schema for a full list of possible values
verification_status
nullablestring
Indicates an Item's micro-deposit-based verification or database verification status. Possible values are:
pending_automatic_verification: The Item is pending automatic verification
pending_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 verified
manually_verified: The Item has successfully been manually verified
verification_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
deprecatednullablestring
If micro-deposit verification was being used, indicates the user's selection when asked if the account being verified is a business or personal account. This field is deprecated as Plaid no longer collects this information during the micro-deposit flow. To see whether an account is business or personal, use the holder_category field instead.
institution
nullableobject
An institution object. If the Item was created via Same-Day or Instant micro-deposit verification, will be null.
name
string
The full institution name, such as 'Wells Fargo'
institution_id
string
The Plaid institution identifier
bank_income_results
[object]
The set of bank income verifications for the Link session.
status
string
Status of the Bank Income Link session.
APPROVED: User has approved and verified their income
NO_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.

Possible values: APPROVED, NO_DEPOSITS_FOUND, USER_REPORTED_NO_INCOME
item_id
string
The Plaid Item ID. The 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
nullableobject
An institution object. If the Item was created via Same-Day or Instant micro-deposit verification, will be null.
name
string
The full institution name, such as 'Wells Fargo'
institution_id
string
The Plaid institution identifier
payroll_income_results
[object]
The set of payroll income verifications for the Link session.
num_paystubs_retrieved
integer
The number of paystubs retrieved from a payroll provider.
num_w2s_retrieved
integer
The number of W-2s retrieved from a payroll provider.
institution
nullableobject
An institution object. If the Item was created via Same-Day or Instant micro-deposit verification, will be null.
name
string
The full institution name, such as 'Wells Fargo'
institution_id
string
The Plaid institution identifier
document_income_results
nullableobject
The details of a document income verification in Link
num_paystubs_uploaded
integer
The number of paystubs uploaded by the user.
num_w2s_uploaded
integer
The number of w2s uploaded by the user.
num_bank_statements_uploaded
integer
The number of bank statements uploaded by the user.
num_1099s_uploaded
integer
The number of 1099s uploaded by the user
cra_document_upload_results
nullableobject
The details of a document upload CRA session in link
num_bank_statements_uploaded
integer
The number of bank statements uploaded by the user.
metadata
object
An object specifying the arguments originally provided to the /link/token/create call.
initial_products
[string]
The products specified in the /link/token/create call.

Possible values: assets, auth, employment, identity, income_verification, identity_verification, investments, liabilities, payment_initiation, standing_orders, transactions, transfer
webhook
nullablestring
The webhook specified in the /link/token/create call.
country_codes
[string]
The country_codes specified in the /link/token/create call.

Possible values: US, GB, ES, NL, FR, IE, CA, DE, IT, PL, DK, NO, SE, EE, LT, LV, PT, BE
language
nullablestring
The language specified in the /link/token/create call.
institution_data
object
A map containing data used to highlight institutions in Link.
routing_number
string
The routing number of the bank to highlight in Link. Note: in rare cases, a single routing number can be associated with multiple institutions, e.g. due to a brokerage using another institution to manage ACH on its sweep accounts. If this happens, the bank will not be highlighted in Link even if the routing number is provided.
account_filters
object
The account_filters specified in the original call to /link/token/create.
depository
object
A filter to apply to depository-type accounts
account_subtypes
[string]
An array of account subtypes to display in Link. If not specified, all account subtypes will be shown. For a full list of valid types and subtypes, see the Account schema.

Possible values: checking, savings, hsa, cd, money market, paypal, prepaid, cash management, ebt, all
credit
object
A filter to apply to credit-type accounts
account_subtypes
[string]
An array of account subtypes to display in Link. If not specified, all account subtypes will be shown. For a full list of valid types and subtypes, see the Account schema.

Possible values: credit card, paypal, all
loan
object
A filter to apply to loan-type accounts
account_subtypes
[string]
An array of account subtypes to display in Link. If not specified, all account subtypes will be shown. For a full list of valid types and subtypes, see the Account schema.

Possible values: auto, business, commercial, construction, consumer, home equity, loan, mortgage, line of credit, student, other, all
investment
object
A filter to apply to investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier).
account_subtypes
[string]
An array of account subtypes to display in Link. If not specified, all account subtypes will be shown. For a full list of valid types and subtypes, see the Account schema.

Possible values: 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
nullablestring
The redirect_uri specified in the /link/token/create call.
client_name
nullablestring
The client_name specified in the /link/token/create call.
user_token
string
The user token associated with the User data is being requested for.
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "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": null
177            },
178            {
179              "class_type": null,
180              "id": "VJyR7wRm79TNGEKxpEG9fjpJ1mmM5Bt9ymVkR",
181              "mask": "1111",
182              "name": "Plaid Saving",
183              "subtype": "savings",
184              "type": "depository",
185              "verification_status": null
186            },
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": null
195            }
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": null
203        },
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": null
218              },
219              {
220                "class_type": null,
221                "id": "VJyR7wRm79TNGEKxpEG9fjpJ1mmM5Bt9ymVkR",
222                "mask": "1111",
223                "name": "Plaid Saving",
224                "subtype": "savings",
225                "type": "depository",
226                "verification_status": null
227              },
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": null
236              }
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": null
254              }
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        "cra_item_add_results": [],
264        "bank_income_results": [],
265        "payroll_income_results": [],
266        "document_income_results": null
267      },
268      "started_at": "2024-07-29T20:22:36.522196741Z"
269    }
270  ],
271  "link_token": "link-sandbox-e7b6956c-1522-4823-85d2-c4ca74251949",
272  "metadata": {
273    "client_name": "Wonderwallet",
274    "country_codes": [
275      "US"
276    ],
277    "initial_products": [
278      "transactions"
279    ],
280    "language": "en",
281    "redirect_uri": null,
282    "webhook": "https://webhook.site/dc9c138f-75de-4db1-883a-a4add4b7eb7e"
283  },
284  "request_id": "Pxpgzy0Wjvn99mY"
285}

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
string
LINK
webhook_code
string
ITEM_ADD_RESULT
link_session_id
string
The identifier for the Link session.
link_token
string
The link token used to create the Link session.
public_token
string
The public token corresponding to the item that was added.
environment
string
The Plaid environment the webhook was sent from

Possible values: 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}

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 sent only for sessions where the end user goes through a Hosted Link flow (including Link Recovery flows). If you would like to receive this webhook for sessions not using Hosted Link, contact your Account Manager or Support.

webhook_type
string
LINK
webhook_code
string
EVENTS
events
[object]
The Link events emitted during the Link session
event_name
string
Event name
timestamp
string
Timestamp in ISO 8601 format.
event_id
string
UUID that can be used to deduplicate events
event_metadata
object
Metadata about an event that occurred while the user was going through Link
error_code
string
The error code that the user encountered. Emitted by ERROR, EXIT.
error_message
string
The error message that the user encountered. Emitted by: ERROR, EXIT.
error_type
string
The error type that the user encountered. Emitted by: ERROR, EXIT.
exit_status
string
The status key indicates the point at which the user exited the Link flow. Emitted by: EXIT.
institution_id
string
The ID of the selected institution. Emitted by: all events.
institution_name
string
The name of the selected institution. Emitted by: all events.
institution_search_query
string
The query used to search for institutions. Emitted by: SEARCH_INSTITUTION.
request_id
string
The request ID for the last request made by Link. This can be shared with Plaid Support to expedite investigation. Emitted by: all events.
mfa_type
string
If set, the user has encountered one of the following MFA types: code, device, questions, selections. Emitted by: SUBMIT_MFA and TRANSITION_VIEW when view_name is MFA.
view_name
string
The name of the view that is being transitioned to. Emitted by: TRANSITION_VIEW.
selection
string
Either the verification method for a matched institution selected by the user or the Auth Type Select flow type selected by the user. If selection is used to describe selected verification method, then possible values are 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
string
The name of the selected brand.
match_reason
string
The reason this institution was matched, which will be either returning_user or routing_number. Emitted by: MATCHED_SELECT_INSTITUTION.
routing_number
string
The routing number submitted by user at the micro-deposits routing number pane. Emitted by SUBMIT_ROUTING_NUMBER.
account_number_mask
string
The account number mask extracted from the user-provided account number. If the user-inputted account number is four digits long, account_number_mask is empty. Emitted by SUBMIT_ACCOUNT_NUMBER.
link_session_id
string
An identifier for the Link session these events occurred in
link_token
string
The Link token used to create the Link session these events are from
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}

SESSION_FINISHED

Contains the state of a completed Link session, along with the public token(s) if available.
By default, this webhook is sent only for sessions enabled for the Hosted Link flow (including Link Recovery flows) or a Multi-Item Link flow. If you would like to receive this webhook for other sessions, contact your Account Manager or Support.

webhook_type
string
LINK
webhook_code
string
SESSION_FINISHED
status
string
The final status of the Link session. Will always be "SUCCESS" or "EXITED".
link_session_id
string
The identifier for the Link session.
link_token
string
The link token used to create the Link session.
public_token
deprecatedstring
The public token generated by the Link session. This field has been deprecated; please use public_tokens instead.
public_tokens
[string]
The public tokens generated by the Link session.
environment
string
The Plaid environment the webhook was sent from

Possible values: 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}