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](https://plaid.com/docs/link/index.html.md) .

| Endpoints |  |
| --- | --- |
| [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) | Create a token for initializing a Link session |
| [/link/token/get](https://plaid.com/docs/api/link/index.html.md#linktokenget) | Get the public token and other details about a completed Link session |

| See also |  |
| --- | --- |
| [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) | Exchange a public token for an access token |
| [/sandbox/public\_token/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxpublic_tokencreate) | Create a public token without the Link flow (Sandbox only) |
| [/sandbox/item/reset\_login](https://plaid.com/docs/api/sandbox/index.html.md#sandboxitemreset_login) | Force an Item into an error state (Sandbox only) |
| [/session/token/create](https://plaid.com/docs/api/products/layer/index.html.md#sessiontokencreate) | Create a session (Layer only) |

| Webhooks |  |
| --- | --- |
| [ITEM\_ADD\_RESULT](https://plaid.com/docs/api/link/index.html.md#item_add_result) | An Item was added during a Link session |
| [EVENTS](https://plaid.com/docs/api/link/index.html.md#events) | Events were received from a Hosted Link session |
| [SESSION\_FINISHED](https://plaid.com/docs/api/link/index.html.md#session_finished) | The user has completed a Link session |

### Endpoints 

\=\*=\*=\*=

#### /link/token/create 

#### Create Link Token 

The [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) 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](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) as part of the main Link flow. For more details, see the [Link flow overview](https://plaid.com/docs/link/index.html.md#link-flow-overview) .

A `link_token` generated by [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) is also used to initialize other Link flows, such as the [update mode](https://plaid.com/docs/link/update-mode/index.html.md) flow for tokens with expired credentials, or the Identity Verification flow.

#### Request fields 

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.

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.

required, string

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`

required, string

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](https://plaid.com/docs/identity-verification/index.html.md#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`

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/. For access to additional countries beyond what you have been approved for, [contact sales](https://plaid.com/contact/) , your account manager, or support.

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. While all countries are enabled by default in Sandbox, in Production only the countries you have requested access for are shown. To request access to additional countries, [file a product access Support ticket](https://dashboard.plaid.com/support/new/product-and-development/product-troubleshooting/request-product-access) 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 Auth, `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`, `AT`, `FI`

object

An object specifying information about the end user who will be linking their account. **Required** if `user_id` isn't included.

required, string

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`

string

The user's full legal name, used for [micro-deposit based verification flows](https://plaid.com/docs/auth/coverage/index.html.md) . 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.

object

The user's full name. Optional if using the [Identity Verification](https://plaid.com/docs/api/products/identity-verification/index.html.md) product; if not using Identity Verification, this field is not allowed. Users will not be asked for their name when this field is provided.

required, string

A string with at least one non-whitespace character, with a max length of 100 characters.

required, string

A string with at least one non-whitespace character, with a max length of 100 characters.

string

The user's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. If supplied, will be used when applicable to prefill phone number fields in Link for the [returning user flow](https://plaid.com/docs/link/returning-user/index.html.md) and the [Identity Verification flow](https://plaid.com/docs/identity-verification/index.html.md) . Phone number input is validated against valid number ranges; number strings that do not match a real-world phone numbering scheme may cause the request to fail, even in the Sandbox test environment.

string

The user's email address. Can be used to prefill Link fields when used with [Identity Verification](https://plaid.com/docs/identity-verification/index.html.md) .

string

To be provided in the format "yyyy-mm-dd". Can be used to prefill Link fields when used with Identity Verification.

Format: `date`

object

The user's address. Used only for Identity Verification and the Identity Match in Link workflows. If provided for Identity Verification, the user will not be shown fields to enter their address in the Identity Verification flow. If provided for Identity Match, the provided data will be used to match against the user's address. May be omitted, but if not omitted, all fields marked as required must be provided.

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.

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.

string

City from the address. A string with at least one non-whitespace alphabetical character, with a max length of 100 characters.

string

A subdivision code. "Subdivision" is a generic term for "state", "province", "prefecture", "zone", etc. For the list of valid codes, see [country subdivision codes](https://plaid.com/documents/country_subdivision_codes.json) . Country prefixes are omitted, since they are inferred from the `country` field.

string

The postal code for the associated address. Between 2 and 10 alphanumeric characters. For US-based addresses this must be 5 numeric digits.

required, string

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

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.

required, string

Value of identity document value typed in by user. Alpha-numeric, with all formatting characters stripped. For specific format requirements by ID type, see [Input Validation Rules](https://plaid.com/docs/identity-verification/hybrid-input-validation/index.html.md#id-numbers) .

required, string

A globally unique and human readable ID type, specific to the country and document category. For more context on this field, see [Input Validation Rules](https://cognitohq.com/docs/flow/flow-hybrid-input-validation#id-numbers) .

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`

string

A `user_id` generated using `/user/create`. Required for integrations that began using Plaid Protect, Multi-Item Link, or Plaid Check Consumer Report after December 10, 2025. For more details, see [new User APIs](https://plaid.com/docs/api/users/user-apis/index.html.md) . One of either the `user_id` or the `user` field is required.

\[string\]

List of Plaid product(s) that the linked Item must support. If launching Link in update mode, should be omitted (unless you are using update mode to add a credit product, such as Assets, Statements, Income, or Plaid Check Consumer Report, to an existing Item); at least one `product` is required otherwise.

To maximize the number of institutions and accounts available, initialize Link with the minimal product set required for your use case, as the products specified will limit which institutions and account types will be available to your users in Link. Only institutions that support _all_ requested products can be selected; 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. For each specified product, the Item connected by the user must contain at least one compatible account. For details on compatible product / account type combinations, see [the account type/product support matrix](https://plaid.com/docs/api/accounts/index.html.md#account-type--product-support-matrix) .

To add products without limiting the institution list or account types, use the [optional\_products](https://plaid.com/docs/api/link/index.html.md#link-token-create-request-optional-products) or [required\_if\_supported\_products](https://plaid.com/docs/api/link/index.html.md#link-token-create-request-required-if-supported-products) fields. Products can also be added to an Item by calling the product endpoint after obtaining an access token; this may require the product to be listed in the [additional\_consented\_products](https://plaid.com/docs/api/link/index.html.md#link-token-create-request-additional-consented-products) array. For details, see [Choosing when to initialize products](https://plaid.com/docs/link/initializing-products/index.html.md) .

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

If launching Link with CRA products, `cra_base_reports` is required and must be included in the `products` array.

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`, `beacon`, `employment`, `identity`, `income_verification`, `identity_verification`, `investments`, `investments_auth`, `liabilities`, `payment_initiation`, `protect_transactions`, `standing_orders`, `signal`, `statements`, `transactions`, `transfer`, `cra_base_report`, `cra_income_insights`, `cra_cashflow_insights`, `cra_lend_score`, `cra_partner_insights`, `cra_network_insights`, `cra_monitoring`, `layer`, `protect_linked_bank`

\[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](https://plaid.com/docs/link/initializing-products/index.html.md#required-if-supported-products) .

Possible values: `auth`, `identity`, `investments`, `liabilities`, `transactions`, `signal`, `statements`, `protect_linked_bank`, `protect_transactions`

\[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](https://plaid.com/docs/link/initializing-products/index.html.md#optional-products) .

Possible values: `auth`, `identity`, `investments`, `liabilities`, `signal`, `statements`, `transactions`, `cra_base_report`, `cra_income_insights`, `cra_cashflow_insights`, `cra_lend_score`, `cra_partner_insights`, `cra_network_insights`, `cra_monitoring`

\[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](https://plaid.com/docs/api/products/signal/index.html.md#signalprepare) before calling `/signal/evaluate` for the first time on an Item in order to get the most accurate results. For more details, see [/signal/prepare](https://plaid.com/docs/api/products/signal/index.html.md#signalprepare) .

Possible values: `auth`, `balance_plus`, `identity`, `investments`, `investments_auth`, `liabilities`, `transactions`, `signal`

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, and Identity Verification 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.

Format: `url`

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`

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

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. Note that any redirect URI must also be added to the Allowed redirect URIs list in the [developer dashboard](https://dashboard.plaid.com/team/api) . If initializing on Android, `android_package_name` must be specified instead and `redirect_uri` should be left blank.

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](https://dashboard.plaid.com/team/api) . 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.

object

A map containing data used to highlight institutions in Link.

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.

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](https://plaid.com/docs/api/accounts/index.html.md#account-type-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.

object

A filter to apply to `depository`\-type accounts

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](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) .

Possible values: `checking`, `savings`, `hsa`, `cd`, `money market`, `paypal`, `prepaid`, `cash management`, `ebt`, `limited purpose checking`, `all`

\[string\]

An array of limited purpose types. Restricts which kinds of limited purpose checking accounts may be connected in Link to prevent users from connecting them for unsupported use cases. Required when 'limited purpose checking' is in the subtypes filter.

Possible values: `RENT_MORTGAGE`

object

A filter to apply to `credit`\-type accounts

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](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) .

Possible values: `credit card`, `paypal`, `all`

object

A filter to apply to `loan`\-type accounts

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](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) .

Possible values: `auto`, `business`, `commercial`, `construction`, `consumer`, `home equity`, `loan`, `mortgage`, `overdraft`, `line of credit`, `student`, `other`, `all`

object

A filter to apply to `investment`\-type accounts (or `brokerage`\-type accounts for API versions 2018-05-22 and earlier).

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](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) .

Possible values: `529`, `401a`, `401k`, `403B`, `457b`, `brokerage`, `cash isa`, `crypto exchange`, `education savings account`, `fhsa`, `fixed annuity`, `gic`, `health reimbursement arrangement`, `hsa`, `ira`, `isa`, `keogh`, `lif`, `life insurance`, `line of credit`, `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`, `roth 403B`, `roth 457b`, `roth pension`, `roth profit sharing plan`, `roth thrift savings plan`, `rrif`, `rrsp`, `sarsep`, `sep ira`, `simple ira`, `sipp`, `stock plan`, `thrift savings plan`, `tfsa`, `trust`, `ugma`, `utma`, `variable annuity`, `all`

object

A filter to apply to `other`\-type accounts

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](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) .

Possible values: `other`, `all`

string

Used for certain legacy use cases

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.

string

The `payment_id` provided by the `/payment_initiation/payment/create` endpoint.

string

The `consent_id` provided by the `/payment_initiation/consent/create` endpoint.

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.

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.

\[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.

\[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`

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

required, integer

The number of days of data to request for the Bank Income product

Minimum: `1`

Maximum: `731`

deprecated, boolean

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`

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](https://dashboard.plaid.com/link) in the Dashboard. (Requires Production enablement.)

\[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`

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`

string

Uniquely identify a payroll income Item to update with. This field is only relevant for participants in the Payroll Income Refresh beta.

\[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`

\[object\]

A list of user stated income sources

string

The employer corresponding to an income source specified by the user

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`

number

The income amount paid per cycle for a specified income source

Format: `double`

number

The income amount paid annually for a specified income source

Format: `double`

string

The pay type - `GROSS`, `NET`, or `UNKNOWN` for a specified income source

Possible values: `UNKNOWN`, `GROSS`, `NET`

string

The pay frequency of a specified income source

Possible values: `UNKNOWN`, `WEEKLY`, `BIWEEKLY`, `SEMI_MONTHLY`, `MONTHLY`

object

Specifies options for initializing Link for use with Plaid Check products

required, integer

The number of days of history to include in Plaid Check products. Maximum is 731; minimum is 180. If a value lower than 180 is provided, a minimum of 180 days of history will be requested.

Maximum: `731`

integer

The minimum number of days of data required for the report to be successfully generated.

Maximum: `184`

string

Client-generated identifier, which can be used by lenders to track loan applications.

object

Specifies options for initializing Link for use with the Credit Partner Insights product.

object

The versions of Prism products to evaluate

string

The version of Prism FirstDetect. If not specified, will default to v3.

Possible values: `3`, `null`

string

The version of Prism Detect

Possible values: `4.1`, `4`, `null`

string

The version of Prism CashScore. If not specified, will default to v3.

Possible values: `4.1`, `4`, `3`, `null`

string

The version of Prism Extend

Possible values: `4.1`, `4`, `null`

string

The version of Prism Insights. If not specified, will default to v3.

Possible values: `4.1`, `4`, `3`, `null`

object

Specifies options for initializing Link for use with the Base Report product, specifically the `client_report_id`.

string

Client-generated identifier, which can be used by lenders to track loan applications.

object

Specifies options for initializing Link to create reports that can be shared with GSEs for mortgage verification.

required, \[string\]

Specifies which types of reports should be made available to GSEs.

Possible values: `VOA`, `EMPLOYMENT_REFRESH`

boolean

Indicates that the report must include identity information. If identity information is not available, the report will fail.

object

Specifies options for initializing Link for use with the Cashflow Insights product.

string

The version of cashflow attributes. Required if using Cash Flow Insights.

Possible values: `CFI1`

object

Specifies options for initializing Link for use with the CRA LendScore product.

string

The version of the LendScore to use. Required if using LendScore.

Possible values: `LS1`

object

Specifies options for initializing Link for use with the CRA Network Insights product.

string

The version of Network Insights. Required if using Network Insights.

Possible values: `NI1`

boolean

Indicates that investment data should be extracted from the linked account(s).

object

Specifies options for initializing Link for use with the CRA Income Insights product.

object

Filters the returned income streams based on the specified income categories. If no filters are requested, streams from the following default set of categories are returned:

*   `EARNED_INCOME.*` (`EARNED_INCOME.SALARY`, `EARNED_INCOME.GIG_ECONOMY`, `EARNED_INCOME.SELF_EMPLOYED`)
*   `BENEFITS.DISABILITY`
*   `RETIREMENT.*` (`RETIREMENT.GOVERNMENT_DERIVED`, `RETIREMENT.PRIVATE_RETIREMENT`, `RETIREMENT.PLAN_DISTRIBUTION`)

The final list of income categories is generated by adding the `included_categories`, then removing the `excluded_categories`. Priority is given to `excluded_categories` in the case of collisions.

Filter patterns supported:

*   `*`: All categories
*   `PRIMARY.*`: All categories within the specified primary category
*   `PRIMARY.SECONDARY`: A specific income category

For a list of income categories, see the [Income V2 Category Taxonomy](https://plaid.com/documents/income-v2-category-taxonomy.csv) .

required, \[string\]

Includes income streams matching the specified categories.

\[string\]

Excludes income streams matching the specified categories.

required, string

The version of Income Insights to use.

Possible values: `II2`

string

Describes the reason you are generating a Consumer Report for this user. When calling `/link/token/create`, this field is required when using Plaid Check (CRA) products; invalid if not using Plaid Check (CRA) products.

`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).

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

`ELIGIBILITY_FOR_GOVT_BENEFITS`: In connection with an eligibility determination for a government benefit where the entity is required to consider an applicant's financial status pursuant to FCRA Section 604(a)(3)(D).

Possible values: `ACCOUNT_REVIEW_CREDIT`, `ACCOUNT_REVIEW_NON_CREDIT`, `EXTENSION_OF_CREDIT`, `LEGITIMATE_BUSINESS_NEED_TENANT_SCREENING`, `LEGITIMATE_BUSINESS_NEED_OTHER`, `WRITTEN_INSTRUCTION_PREQUALIFICATION`, `WRITTEN_INSTRUCTION_OTHER`, `ELIGIBILITY_FOR_GOVT_BENEFITS`

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. If you have enabled the [Dashboard Account Verification pane](https://dashboard.plaid.com/account-verification) , the settings enabled there will override any settings in this object.

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

boolean

Specifies whether the Link session is enabled for the Automated Micro-deposits flow. Default behavior is `false`.

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

boolean

Specifies whether the Link session is enabled for the Same Day Micro-deposits flow. Default behavior is `false`.

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

string

Specifies what type of [Reroute to Credentials](https://plaid.com/docs/auth/coverage/flow-options/index.html.md#removing-manual-verification-entry-points-with-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`

deprecated, boolean

Database Match has been deprecated and replaced with Database Auth. Use the [Account Verification Dashboard](https://dashboard.plaid.com/account-verification) to enable Database Auth.

deprecated, boolean

Database Insights has been deprecated and replaced with Database Auth. Use the [Account Verification Dashboard](https://dashboard.plaid.com/account-verification) to enable Database Auth.

boolean

Specifies whether the Link session is enabled for SMS micro-deposits verification. Default behavior is `true`.

object

Specifies options for initializing Link for use with the Transfer product.

string

The `id` returned by the `/transfer/intent/create` endpoint.

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.

object

Specifies options for initializing Link for [update mode](https://plaid.com/docs/link/update-mode/index.html.md) .

boolean

If `true`, enables [update mode with Account Select](https://plaid.com/docs/link/update-mode/index.html.md#using-update-mode-to-request-new-accounts) 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`

boolean

If `true`, a `user_token` must also be provided, and Link will open in update mode for the given user.

Default: `false`

\[string\]

An array of `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.

object

Specifies option for initializing Link for use with the Identity Verification product.

required, string

ID of the associated Identity Verification template. Like all Plaid identifiers, this is case-sensitive.

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`

object

Specifies options for initializing Link for use with the Statements product. This field is required for the statements product.

required, string

The start date for statements, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) "YYYY-MM-DD" format, e.g. "2020-10-30".

Format: `date`

required, string

The end date for statements, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) "YYYY-MM-DD" format, e.g. "2020-10-30". You can request up to two years of data.

Format: `date`

object

Configuration parameters for the Investments product

boolean

If `true`, allow self-custody crypto wallets to be added without requiring signature verification. Defaults to `false`.

boolean

If `true`, allow users to manually enter Investments account and holdings information. Defaults to `false`.

object

Configuration parameters for the Investments Move product

boolean

If `true`, show institutions that use the manual entry fallback flow.

Default: `false`

boolean

If `true`, show institutions that use the masked number match fallback flow.

Default: `false`

boolean

If `true`, show institutions that use the stated account number fallback flow.

Default: `false`

object

Configuration parameters for Hosted Link. To enable the session for Hosted Link, send this object in the request. It can be empty.

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`

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.

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.

boolean

This indicates whether the client is opening hosted Link in a mobile app in an `AsWebAuthenticationSession` or Chrome custom tab.

Default: `false`

object

Configuration parameters for the Transactions product

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. In Production, 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](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsrecurringget) should request at least 180 days of history for optimal results.

Minimum: `1`

Maximum: `730`

Default: `90`

object

Identity object used to specify document upload

boolean

Used to specify whether the Link session is Identity Document Upload

\[string\]

An array of `account_ids`. Currently can only contain one `account_id`. Must be populated if using Document Upload.

\[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`

boolean

If `true`, enable linking multiple items in the same Link session. Defaults to `false`.

string

A user token generated using `/user/create`. Any Item created during the Link session will be associated with the user. Integrations that began using Plaid Protect, Multi-Item Link, or Plaid Check Consumer Report before December 10, 2025 use this field instead of the `user_id`.

```node
const request: LinkTokenCreateRequest = {
  loading_sample: true
};
try {
  const response = await plaidClient.linkTokenCreate(request);
  const linkToken = response.data.link_token;
} catch (error) {
  // handle error
}
```

```python
request = LinkTokenCreateRequest(
  loading_sample=True
)
# create link token
response = client.link_token_create(request)
link_token = response['link_token']
```

```bash
curl -X POST https://sandbox.plaid.com/link/token/create -H 'Content-Type: application/json' -d '{
  "client_id": "${PLAID_CLIENT_ID}",
  "secret": "${PLAID_SECRET}",
  "loading_sample": true
}'
```

```ruby
link_token_create_request = Plaid::LinkTokenCreateRequest.new(
  {
    loading_sample: true
  }
)

response = client.link_token_create(
  link_token_create_request
)
link_token = response.link_token
```

```java
LinkTokenCreateRequest request = new LinkTokenCreateRequest()
  .loadingSample(true);

Response response = client
  .linkTokenCreate(request)
  .execute();

String linkToken = response.body().getLinkToken();
```

```go
request := plaid.NewLinkTokenCreateRequest(
  "Sample App App",
  "en",
  []plaid.CountryCode{plaid.COUNTRYCODE_US},
  user,
)
request.SetLoadingSample(true)

linkTokenCreateResp, _, err := client.PlaidApi.LinkTokenCreate(ctx).LinkTokenCreateRequest(*request).Execute()
if err != nil {
  panic(err)
}
linkToken := linkTokenCreateResp.GetLinkToken();
```

#### Response fields 

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

string

The expiration date and time for the `link_token`, in [ISO 8601](https://wikipedia.org/wiki/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](https://plaid.com/docs/link/hosted-link/index.html.md) , 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. If using Identity Verification, Link token expiration will not be enforced; an Identity Verification Link session can be created with an expired Link token.

Format: `date-time`

string

A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

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.

string

A unique user identifier, created by `/user/create`. Integrations that began using `/user/create` after December 10, 2025 use this field to identify a user instead of the `user_token`. For more details, see [new user APIs](https://plaid.com/docs/api/users/user-apis/index.html.md) .

Response Object

```json
{
  "link_token": "link-sandbox-af1a0311-da53-4636-b754-dd15cc058176",
  "expiration": "2020-03-27T12:56:34Z",
  "request_id": "XQVgFigpGHXkb0b"
}
```

\=\*=\*=\*=

#### /link/token/get 

#### Get Link Token 

The [/link/token/get](https://plaid.com/docs/api/link/index.html.md#linktokenget) 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](https://plaid.com/docs/link/hosted-link/index.html.md) and the [Multi-Item Link flow](https://plaid.com/docs/link/multi-item-link/index.html.md) . It also can be useful for debugging purposes.

By default, this endpoint will only return complete event data for Hosted Link sessions. To use [/link/token/get](https://plaid.com/docs/api/link/index.html.md#linktokenget) to retrieve event data for non-Hosted-Link sessions, contact your account manager to request that your account be enabled for Link events. If you do not have an account manager, you can submit this request via a support ticket. Enablement for Link events will also cause you to receive additional webhooks related to Link events, such as the `SESSION_FINISHED` and `EVENTS` webhook.

#### Request fields 

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.

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.

required, string

A `link_token` from a previous invocation of `/link/token/create`

```ruby
request = Plaid::LinkTokenGetRequest.new({ link_token: link_token })
response = client.link_token_get(request)

```

```go
linkTokenGetRequest := plaid.NewLinkTokenGetRequest(linkToken)
linkTokenGetResp, _, err := client.PlaidApi.LinkTokenGet(ctx).LinkTokenGetRequest(*linkTokenGetRequest).Execute()

```

```java
LinkTokenGetRequest request = new LinkTokenGetRequest()
  .linkToken(linkToken);
Response getResponse = client()
  .linkTokenGet(request)
  .execute();

```

```python
request = LinkTokenGetRequest(link_token=link_token)
response = client.link_token_get(request)

```

```node
const request: LinkTokenGetRequest = {
  link_token: linkToken,
};
try {
  const response = await plaidClient.linkTokenGet(request);
} catch (error) {
  // handle error
}

```

```bash
curl -X POST https://sandbox.plaid.com/link/token/get -H 'Content-Type: application/json' -d '{
  "client_id": "${PLAID_CLIENT_ID}",
  "secret": "${PLAID_SECRET}",
  "link_token": "${LINK_TOKEN}"
}'

```

#### Response fields 

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

nullable, string

The creation timestamp for the `link_token`, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format.

Format: `date-time`

nullable, string

The expiration timestamp for the `link_token`, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format.

Format: `date-time`

\[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.

string

The unique ID for the link session.

string

The timestamp at which the link session was first started, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format.

Format: `date-time`

nullable, string

The timestamp at which the link session was finished, if available, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format.

Format: `date-time`

deprecated, nullable, object

An object representing an [onSuccess](https://plaid.com/docs/link/web/index.html.md#onsuccess) callback from Link. This field is returned only for legacy integrations and is deprecated in favor of [results.item\_add\_results](https://plaid.com/docs/api/link/index.html.md#link-token-get-response-link-sessions-results-item-add-results) which can support multiple public tokens in a single Link session, for flows such as multi-Item Link. If you are receiving `on_success`, contact your account manager to migrate to `results.item_add_results` instead.

string

Displayed once a user has successfully linked their Item.

nullable, object

Displayed once a user has successfully linked their Item.

nullable, object

An institution object. If the Item was created via Same-Day or Instant micro-deposit verification, will be `null`.

string

The full institution name, such as `'Wells Fargo'`

string

The Plaid institution identifier

\[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.

string

The Plaid `account_id`

string

The official account name

nullable, string

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.

string

The account type. See the [Account schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full list of possible values

string

The account subtype. See the [Account schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full list of possible values

nullable, string

Indicates an Item's micro-deposit-based verification or database verification status. This field is only populated when using Auth and falling back to micro-deposit or database verification. 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.

`unsent`: The Item is pending micro-deposit verification, but Plaid has not yet sent the micro-deposit.

`database_insights_pending`: The Database Auth result is pending and will be available upon Auth request.

`database_insights_fail`: The Item's numbers have been verified using Plaid's data sources and have signal for being invalid and/or have no signal for being valid. Typically this indicates that the routing number is invalid, the account number does not match the account number format associated with the routing number, or the account has been reported as closed or frozen. Only returned for Auth Items created via Database Auth.

`database_insights_pass`: The Item's numbers have been verified using Plaid's data sources: the routing and account number match a routing and account number of an account recognized on the Plaid network, and the account is not known by Plaid to be frozen or closed. Only returned for Auth Items created via Database Auth.

`database_insights_pass_with_caution`: The Item's numbers have been verified using Plaid's data sources and have some signal for being valid: the routing and account number were not recognized on the Plaid network, but the routing number is valid and the account number is a potential valid account number for that routing number. Only returned for Auth Items created via Database Auth.

`database_matched`: (deprecated) The Item has successfully been verified using Plaid's data sources. Only returned for Auth Items created via Database Match.

`null` or empty string: Neither micro-deposit-based verification nor database verification are being used for the Item.

deprecated, nullable, string

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.

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.

nullable, string

The status of a transfer. Returned only when [Transfer UI](https://plaid.com/docs/transfer/using-transfer-ui/index.html.md) is implemented.

*   `COMPLETE` - The transfer was completed.
*   `INCOMPLETE` - The transfer could not be completed. For help, see [Troubleshooting transfers](https://plaid.com/docs/transfer/using-transfer-ui/index.html.md#troubleshooting-transfer-ui) .

Possible values: `COMPLETE`, `INCOMPLETE`, `null`

deprecated, nullable, object

An object representing an [onExit](https://plaid.com/docs/link/web/index.html.md#onexit) callback from Link. This field is returned only for legacy implementations and has been deprecated in favor of [exit](https://plaid.com/docs/api/link/index.html.md#link-token-get-response-link-sessions-exit) , for improved naming consistency. If you are receiving this field, contact your account manager to migrate to the newer `exit` field.

nullable, object

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.

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`, `SIGNAL_ERROR`, `TRANSACTIONS_ERROR`, `TRANSACTION_ERROR`, `TRANSFER_ERROR`, `CHECK_REPORT_ERROR`, `CONSUMER_REPORT_ERROR`, `USER_ERROR`

string

The particular error code. Safe for programmatic use.

nullable, string

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.

string

A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.

nullable, string

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.

string

A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks.

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 be provided for the `error_type` `ASSET_REPORT_ERROR` or `CHECK_REPORT_ERROR`. `causes` will also not be populated inside an error nested within a `warning` object.

nullable, integer

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.

string

The URL of a Plaid documentation page with more information about the error

nullable, string

Suggested steps for resolving the error

\[string\]

A list of the account subtypes that were requested via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product.

\[string\]

A list of the account subtypes that were extracted but did not match the requested subtypes via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product.

nullable, object

Displayed if a user exits Link without successfully linking an Item.

nullable, object

An institution object. If the Item was created via Same-Day or Instant micro-deposit verification, will be `null`.

string

The full institution name, such as `Wells Fargo`

string

The Plaid institution identifier

string

The point at which the user exited the Link flow. One of the following values.

User prompted to answer security questions

User prompted to answer multiple choice question(s)

User prompted to provide a one-time passcode

User prompted to select a device on which to receive a one-time passcode

User prompted to provide credentials for the selected financial institution or has not yet selected a financial institution

User prompted to select one or more financial accounts to share

User prompted to enter an OAuth flow

User exited the Link flow after unsuccessfully (no results returned) searching for a financial institution

User exited the Link flow after discovering their selected institution is no longer supported by Plaid

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.

string

The request ID for the last request made by Link. This can be shared with Plaid support to expedite investigation.

nullable, object

An object representing an [onExit](https://plaid.com/docs/link/web/index.html.md#onexit) callback from Link. If you are not receiving this field and are instead receiving the deprecated `on_exit` field, contact your account manager to update your integration.

nullable, object

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.

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`, `SIGNAL_ERROR`, `TRANSACTIONS_ERROR`, `TRANSACTION_ERROR`, `TRANSFER_ERROR`, `CHECK_REPORT_ERROR`, `CONSUMER_REPORT_ERROR`, `USER_ERROR`

string

The particular error code. Safe for programmatic use.

nullable, string

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.

string

A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.

nullable, string

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.

string

A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks.

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 be provided for the `error_type` `ASSET_REPORT_ERROR` or `CHECK_REPORT_ERROR`. `causes` will also not be populated inside an error nested within a `warning` object.

nullable, integer

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.

string

The URL of a Plaid documentation page with more information about the error

nullable, string

Suggested steps for resolving the error

\[string\]

A list of the account subtypes that were requested via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product.

\[string\]

A list of the account subtypes that were extracted but did not match the requested subtypes via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product.

nullable, object

Displayed if a user exits Link without successfully linking an Item.

nullable, object

An institution object. If the Item was created via Same-Day or Instant micro-deposit verification, will be `null`.

string

The full institution name, such as `Wells Fargo`

string

The Plaid institution identifier

string

The point at which the user exited the Link flow. One of the following values.

User prompted to answer security questions

User prompted to answer multiple choice question(s)

User prompted to provide a one-time passcode

User prompted to select a device on which to receive a one-time passcode

User prompted to provide credentials for the selected financial institution or has not yet selected a financial institution

User prompted to select one or more financial accounts to share

User prompted to enter an OAuth flow

User exited the Link flow after unsuccessfully (no results returned) searching for a financial institution

User exited the Link flow after discovering their selected institution is no longer supported by Plaid

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.

string

The request ID for the last request made by Link. This can be shared with Plaid support to expedite investigation.

\[object\]

List of customer-related Link events

string

Event name

string

Timestamp in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format.

string

UUID that can be used to deduplicate events

object

Metadata about an event that occurred while the user was going through Link

string

The error code that the user encountered. Emitted by `ERROR`, `EXIT`.

string

The error message that the user encountered. Emitted by: `ERROR`, `EXIT`.

string

The error type that the user encountered. Emitted by: `ERROR`, `EXIT`.

string

The status key indicates the point at which the user exited the Link flow. Emitted by: `EXIT`.

string

The ID of the selected institution. Emitted by: all events.

string

The name of the selected institution. Emitted by: all events.

string

The query used to search for institutions. Emitted by: `SEARCH_INSTITUTION`.

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.

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

string

The name of the view that is being transitioned to. Emitted by: `TRANSITION_VIEW`.

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

string

The name of the selected brand.

string

The reason this institution was matched. This will be either `returning_user` or `routing_number` if emitted by `MATCHED_SELECT_INSTITUTION`. Otherwise, this will be `SAVED_INSTITUTION` or `AUTO_SELECT_SAVED_INSTITUTION` if emitted by `SELECT_INSTITUTION`.

string

The routing number submitted by user at the micro-deposits routing number pane. Emitted by `SUBMIT_ROUTING_NUMBER`.

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

nullable, object

The set of results for a Link session.

\[object\]

The set of Item adds for the Link session. If you are not receiving this field and are instead receiving the deprecated `on_success` field, contact your account manager to update your integration.

string

Returned once a user has successfully linked their Item.

\[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.

string

The Plaid `account_id`

string

The official account name

nullable, string

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.

string

The account type. See the [Account schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full list of possible values

string

The account subtype. See the [Account schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full list of possible values

nullable, string

Indicates an Item's micro-deposit-based verification or database verification status. This field is only populated when using Auth and falling back to micro-deposit or database verification. 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.

`unsent`: The Item is pending micro-deposit verification, but Plaid has not yet sent the micro-deposit.

`database_insights_pending`: The Database Auth result is pending and will be available upon Auth request.

`database_insights_fail`: The Item's numbers have been verified using Plaid's data sources and have signal for being invalid and/or have no signal for being valid. Typically this indicates that the routing number is invalid, the account number does not match the account number format associated with the routing number, or the account has been reported as closed or frozen. Only returned for Auth Items created via Database Auth.

`database_insights_pass`: The Item's numbers have been verified using Plaid's data sources: the routing and account number match a routing and account number of an account recognized on the Plaid network, and the account is not known by Plaid to be frozen or closed. Only returned for Auth Items created via Database Auth.

`database_insights_pass_with_caution`: The Item's numbers have been verified using Plaid's data sources and have some signal for being valid: the routing and account number were not recognized on the Plaid network, but the routing number is valid and the account number is a potential valid account number for that routing number. Only returned for Auth Items created via Database Auth.

`database_matched`: (deprecated) The Item has successfully been verified using Plaid's data sources. Only returned for Auth Items created via Database Match.

`null` or empty string: Neither micro-deposit-based verification nor database verification are being used for the Item.

deprecated, nullable, string

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.

nullable, object

An institution object. If the Item was created via Same-Day or Instant micro-deposit verification, will be `null`.

string

The full institution name, such as `'Wells Fargo'`

string

The Plaid institution identifier

\[object\]

The set of Plaid Check Item adds for the Link session.

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.

\[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.

string

The Plaid `account_id`

string

The official account name

nullable, string

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.

string

The account type. See the [Account schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full list of possible values

string

The account subtype. See the [Account schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full list of possible values

nullable, string

Indicates an Item's micro-deposit-based verification or database verification status. This field is only populated when using Auth and falling back to micro-deposit or database verification. 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.

`unsent`: The Item is pending micro-deposit verification, but Plaid has not yet sent the micro-deposit.

`database_insights_pending`: The Database Auth result is pending and will be available upon Auth request.

`database_insights_fail`: The Item's numbers have been verified using Plaid's data sources and have signal for being invalid and/or have no signal for being valid. Typically this indicates that the routing number is invalid, the account number does not match the account number format associated with the routing number, or the account has been reported as closed or frozen. Only returned for Auth Items created via Database Auth.

`database_insights_pass`: The Item's numbers have been verified using Plaid's data sources: the routing and account number match a routing and account number of an account recognized on the Plaid network, and the account is not known by Plaid to be frozen or closed. Only returned for Auth Items created via Database Auth.

`database_insights_pass_with_caution`: The Item's numbers have been verified using Plaid's data sources and have some signal for being valid: the routing and account number were not recognized on the Plaid network, but the routing number is valid and the account number is a potential valid account number for that routing number. Only returned for Auth Items created via Database Auth.

`database_matched`: (deprecated) The Item has successfully been verified using Plaid's data sources. Only returned for Auth Items created via Database Match.

`null` or empty string: Neither micro-deposit-based verification nor database verification are being used for the Item.

deprecated, nullable, string

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.

nullable, object

An institution object. If the Item was created via Same-Day or Instant micro-deposit verification, will be `null`.

string

The full institution name, such as `'Wells Fargo'`

string

The Plaid institution identifier

\[object\]

The set of Plaid Check Item updates for the Link session.

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.

\[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.

string

The Plaid `account_id`

string

The official account name

nullable, string

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.

string

The account type. See the [Account schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full list of possible values

string

The account subtype. See the [Account schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full list of possible values

nullable, string

Indicates an Item's micro-deposit-based verification or database verification status. This field is only populated when using Auth and falling back to micro-deposit or database verification. 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.

`unsent`: The Item is pending micro-deposit verification, but Plaid has not yet sent the micro-deposit.

`database_insights_pending`: The Database Auth result is pending and will be available upon Auth request.

`database_insights_fail`: The Item's numbers have been verified using Plaid's data sources and have signal for being invalid and/or have no signal for being valid. Typically this indicates that the routing number is invalid, the account number does not match the account number format associated with the routing number, or the account has been reported as closed or frozen. Only returned for Auth Items created via Database Auth.

`database_insights_pass`: The Item's numbers have been verified using Plaid's data sources: the routing and account number match a routing and account number of an account recognized on the Plaid network, and the account is not known by Plaid to be frozen or closed. Only returned for Auth Items created via Database Auth.

`database_insights_pass_with_caution`: The Item's numbers have been verified using Plaid's data sources and have some signal for being valid: the routing and account number were not recognized on the Plaid network, but the routing number is valid and the account number is a potential valid account number for that routing number. Only returned for Auth Items created via Database Auth.

`database_matched`: (deprecated) The Item has successfully been verified using Plaid's data sources. Only returned for Auth Items created via Database Match.

`null` or empty string: Neither micro-deposit-based verification nor database verification are being used for the Item.

deprecated, nullable, string

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.

nullable, object

An institution object. If the Item was created via Same-Day or Instant micro-deposit verification, will be `null`.

string

The full institution name, such as `'Wells Fargo'`

string

The Plaid institution identifier

\[object\]

The set of bank income verifications for the Link session.

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`

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.

nullable, object

An institution object. If the Item was created via Same-Day or Instant micro-deposit verification, will be `null`.

string

The full institution name, such as `'Wells Fargo'`

string

The Plaid institution identifier

\[object\]

The set of payroll income verifications for the Link session.

integer

The number of paystubs retrieved from a payroll provider.

integer

The number of W-2s retrieved from a payroll provider.

nullable, object

An institution object. If the Item was created via Same-Day or Instant micro-deposit verification, will be `null`.

string

The full institution name, such as `'Wells Fargo'`

string

The Plaid institution identifier

nullable, object

The details of a document income verification in Link

integer

The number of paystubs uploaded by the user.

integer

The number of w2s uploaded by the user.

integer

The number of bank statements uploaded by the user.

integer

The number of 1099s uploaded by the user

nullable, object

The details of a document upload CRA session in link

integer

The number of bank statements uploaded by the user.

object

An object specifying the arguments originally provided to the `/link/token/create` call.

\[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`

nullable, string

The `webhook` specified in the `/link/token/create` call.

Format: `url`

\[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`, `AT`, `FI`

nullable, string

The `language` specified in the `/link/token/create` call.

object

A map containing data used to highlight institutions in Link.

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.

object

The `account_filters` specified in the original call to `/link/token/create`.

object

A filter to apply to `depository`\-type accounts

\[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](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) .

Possible values: `checking`, `savings`, `hsa`, `cd`, `money market`, `paypal`, `prepaid`, `cash management`, `ebt`, `limited purpose checking`, `all`

\[string\]

An array of limited purpose types. Restricts which kinds of limited purpose checking accounts may be connected in Link to prevent users from connecting them for unsupported use cases. Required when 'limited purpose checking' is in the subtypes filter.

Possible values: `RENT_MORTGAGE`

object

A filter to apply to `credit`\-type accounts

\[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](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) .

Possible values: `credit card`, `paypal`, `all`

object

A filter to apply to `loan`\-type accounts

\[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](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) .

Possible values: `auto`, `business`, `commercial`, `construction`, `consumer`, `home equity`, `loan`, `mortgage`, `overdraft`, `line of credit`, `student`, `other`, `all`

object

A filter to apply to `investment`\-type accounts (or `brokerage`\-type accounts for API versions 2018-05-22 and earlier).

\[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](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) .

Possible values: `529`, `401a`, `401k`, `403B`, `457b`, `brokerage`, `cash isa`, `crypto exchange`, `education savings account`, `fhsa`, `fixed annuity`, `gic`, `health reimbursement arrangement`, `hsa`, `ira`, `isa`, `keogh`, `lif`, `life insurance`, `line of credit`, `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`, `roth 403B`, `roth 457b`, `roth pension`, `roth profit sharing plan`, `roth thrift savings plan`, `rrif`, `rrsp`, `sarsep`, `sep ira`, `simple ira`, `sipp`, `stock plan`, `thrift savings plan`, `tfsa`, `trust`, `ugma`, `utma`, `variable annuity`, `all`

nullable, string

The `redirect_uri` specified in the `/link/token/create` call.

nullable, string

The `client_name` specified in the `/link/token/create` call.

string

A unique user identifier, created by `/user/create`. Integrations that began using `/user/create` after December 10, 2025 use this field to identify a user instead of the `user_token`. For more details, see [new user APIs](https://plaid.com/docs/api/users/user-apis/index.html.md) .

string

A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

Response Object

```json
{
  "created_at": "2024-07-29T20:22:21Z",
  "expiration": "2024-07-29T20:52:22Z",
  "link_sessions": [
    {
      "events": [
        {
          "event_id": "8b2b5d28-79ec-468b-bbce-f8bd34be635a",
          "event_metadata": {
            "institution_id": "ins_20",
            "institution_name": "Citizens Bank",
            "request_id": "Nnclj9HntPMu5dm"
          },
          "event_name": "HANDOFF",
          "timestamp": "2024-07-29T20:23:59Z"
        },
        {
          "event_id": "12a888e0-da26-4c38-8ded-2992bc78c246",
          "event_metadata": {
            "request_id": "Nnclj9HntPMu5dm"
          },
          "event_name": "TRANSITION_VIEW",
          "timestamp": "2024-07-29T20:23:59Z"
        },
        {
          "event_id": "6557bdf1-a20a-43b0-8fed-c8b671e2f478",
          "event_metadata": {
            "institution_id": "ins_20",
            "institution_name": "Citizens Bank",
            "request_id": "sR4EGcU8zniznXi"
          },
          "event_name": "TRANSITION_VIEW",
          "timestamp": "2024-07-29T20:23:56Z"
        },
        {
          "event_id": "c6745f4c-d8fa-4103-8a65-7b995c60809e",
          "event_metadata": {
            "institution_id": "ins_20",
            "institution_name": "Citizens Bank",
            "request_id": "4LYDWkxfJ0htDA4"
          },
          "event_name": "SUBMIT_CREDENTIALS",
          "timestamp": "2024-07-29T20:23:55Z"
        },
        {
          "event_id": "2610fa06-e765-4c9e-8948-63048d451dbf",
          "event_metadata": {
            "institution_id": "ins_20",
            "institution_name": "Citizens Bank",
            "request_id": "4LYDWkxfJ0htDA4"
          },
          "event_name": "TRANSITION_VIEW",
          "timestamp": "2024-07-29T20:23:23Z"
        },
        {
          "event_id": "54b87deb-60a7-4f50-9326-293840090b72",
          "event_metadata": {
            "institution_id": "ins_20",
            "institution_name": "Citizens Bank",
            "request_id": "FTEFiPeL9OstwL4"
          },
          "event_name": "SELECT_INSTITUTION",
          "timestamp": "2024-07-29T20:23:23Z"
        },
        {
          "event_id": "6b285180-0bac-4ccc-bec0-d4ed75c253d2",
          "event_metadata": {
            "request_id": "FTEFiPeL9OstwL4"
          },
          "event_name": "TRANSITION_VIEW",
          "timestamp": "2024-07-29T20:23:20Z"
        },
        {
          "event_id": "239a6000-da50-4319-99f7-919378b7db53",
          "event_metadata": {
            "request_id": "WFgwgGivjBbwOb9"
          },
          "event_name": "TRANSITION_VIEW",
          "timestamp": "2024-07-29T20:23:17Z"
        },
        {
          "event_id": "0a523744-5003-4578-8414-c87e06ef8ca9",
          "event_metadata": {
            "institution_id": "ins_127989",
            "institution_name": "Bank of America",
            "request_id": "WFgwgGivjBbwOb9"
          },
          "event_name": "HANDOFF",
          "timestamp": "2024-07-29T20:23:17Z"
        },
        {
          "event_id": "ff44d52a-51ef-4987-b7d0-b6497dfa93cd",
          "event_metadata": {
            "institution_id": "ins_127989",
            "institution_name": "Bank of America",
            "request_id": "uqA0Vq8zuKlsB2y"
          },
          "event_name": "TRANSITION_VIEW",
          "timestamp": "2024-07-29T20:23:14Z"
        },
        {
          "event_id": "e0d7c1dc-8e7e-4361-893f-d6c2d2f050ab",
          "event_metadata": {
            "institution_id": "ins_127989",
            "institution_name": "Bank of America",
            "request_id": "dTGtMHbK21BLrsp"
          },
          "event_name": "OPEN_OAUTH",
          "timestamp": "2024-07-29T20:22:49Z"
        },
        {
          "event_id": "de87a1c0-666e-4d95-88d8-1163f6bf20f1",
          "event_metadata": {
            "institution_id": "ins_127989",
            "institution_name": "Bank of America",
            "request_id": "dTGtMHbK21BLrsp"
          },
          "event_name": "TRANSITION_VIEW",
          "timestamp": "2024-07-29T20:22:47Z"
        },
        {
          "event_id": "6edc2c59-96cd-4dee-a86b-140ddfd3076e",
          "event_metadata": {
            "institution_id": "ins_127989",
            "institution_name": "Bank of America",
            "request_id": "BxBukZsBEmxZw0I"
          },
          "event_name": "SELECT_INSTITUTION",
          "timestamp": "2024-07-29T20:22:46Z"
        },
        {
          "event_id": "d176ab57-26d2-45ee-a0fe-67daf0cf0cb0",
          "event_metadata": {
            "request_id": "BxBukZsBEmxZw0I"
          },
          "event_name": "TRANSITION_VIEW",
          "timestamp": "2024-07-29T20:22:43Z"
        },
        {
          "event_id": "b8be9c3d-7ac5-4851-bd92-0638cb63bdeb",
          "event_metadata": {
            "request_id": "UtqR09RKzJ1gcEx"
          },
          "event_name": "SKIP_SUBMIT_PHONE",
          "timestamp": "2024-07-29T20:22:42Z"
        },
        {
          "event_id": "7144cca7-533b-4dfc-81ed-f78a750ba95f",
          "event_metadata": {
            "request_id": "UtqR09RKzJ1gcEx"
          },
          "event_name": "TRANSITION_VIEW",
          "timestamp": "2024-07-29T20:22:40Z"
        },
        {
          "event_id": "e6a6dcc0-6bbf-4871-8d59-0c3a5eccff53",
          "event_metadata": {
            "request_id": "FTiagIVmxfqbevM"
          },
          "event_name": "TRANSITION_VIEW",
          "timestamp": "2024-07-29T20:22:39Z"
        }
      ],
      "finished_at": "2024-07-29T20:24:05.330312653Z",
      "link_session_id": "43face8b-a5c2-42a4-adec-4a4ec589eb46",
      "on_success": {
        "metadata": {
          "accounts": [
            {
              "class_type": null,
              "id": "DXzZ94ZG9vhaZy8BvyZRSQ4jJwwlkNS3RwoeX",
              "mask": "0000",
              "name": "Plaid Checking",
              "subtype": "checking",
              "type": "depository",
              "verification_status": null
            },
            {
              "class_type": null,
              "id": "VJyR7wRm79TNGEKxpEG9fjpJ1mmM5Bt9ymVkR",
              "mask": "1111",
              "name": "Plaid Saving",
              "subtype": "savings",
              "type": "depository",
              "verification_status": null
            },
            {
              "class_type": null,
              "id": "wZXnexn1eoH6LNWmMNL4hqkPB55ndjHPRNp93",
              "mask": "9999",
              "name": "Plaid Business Credit Card",
              "subtype": "credit card",
              "type": "credit",
              "verification_status": null
            }
          ],
          "institution": {
            "institution_id": "ins_127989",
            "name": "Bank of America"
          },
          "link_session_id": "43face8b-a5c2-42a4-adec-4a4ec589eb46",
          "transfer_status": null
        },
        "public_token": "public-sandbox-3b9687f0-3abd-4913-9889-f0ba816d4a3a"
      },
      "results": {
        "item_add_results": [
          {
            "accounts": [
              {
                "class_type": null,
                "id": "DXzZ94ZG9vhaZy8BvyZRSQ4jJwwlkNS3RwoeX",
                "mask": "0000",
                "name": "Plaid Checking",
                "subtype": "checking",
                "type": "depository",
                "verification_status": null
              },
              {
                "class_type": null,
                "id": "VJyR7wRm79TNGEKxpEG9fjpJ1mmM5Bt9ymVkR",
                "mask": "1111",
                "name": "Plaid Saving",
                "subtype": "savings",
                "type": "depository",
                "verification_status": null
              },
              {
                "class_type": null,
                "id": "wZXnexn1eoH6LNWmMNL4hqkPB55ndjHPRNp93",
                "mask": "9999",
                "name": "Plaid Business Credit Card",
                "subtype": "credit card",
                "type": "credit",
                "verification_status": null
              }
            ],
            "institution": {
              "institution_id": "ins_127989",
              "name": "Bank of America"
            },
            "public_token": "public-sandbox-3b9687f0-3abd-4913-9889-f0ba816d4a3a"
          },
          {
            "accounts": [
              {
                "class_type": null,
                "id": "qvqrX8gDvxCdyvvgGkKzSNPzDwaQGjFgyQk5Z",
                "mask": "4007",
                "name": "Checking",
                "subtype": "checking",
                "type": "depository",
                "verification_status": null
              }
            ],
            "institution": {
              "institution_id": "ins_20",
              "name": "Citizens Bank"
            },
            "public_token": "public-sandbox-44ba202e-bf6b-45c6-a5ba-d526765626a9"
          }
        ],
        "cra_item_add_results": [],
        "cra_update_results": [],
        "bank_income_results": [],
        "payroll_income_results": [],
        "document_income_results": null,
        "protect_results": null
      },
      "started_at": "2024-07-29T20:22:36.522196741Z"
    }
  ],
  "link_token": "link-sandbox-e7b6956c-1522-4823-85d2-c4ca74251949",
  "metadata": {
    "client_name": "Wonderwallet",
    "country_codes": [
      "US"
    ],
    "initial_products": [
      "transactions"
    ],
    "language": "en",
    "redirect_uri": null,
    "webhook": "https://webhook.site/dc9c138f-75de-4db1-883a-a4add4b7eb7e"
  },
  "user_id": "usr_123456abcdef",
  "request_id": "Pxpgzy0Wjvn99mY"
}
```

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

#### Properties 

string

`LINK`

string

`ITEM_ADD_RESULT`

string

The identifier for the Link session.

string

The link token used to create the Link session.

string

The public token corresponding to the item that was added.

string

The Plaid environment the webhook was sent from

Possible values: `sandbox`, `production`

API Object

```json
{
  "webhook_type": "LINK",
  "webhook_code": "ITEM_ADD_RESULT",
  "link_session_id": "356dbb28-7f98-44d1-8e6d-0cec580f3171",
  "link_token": "link-sandbox-af1a0311-da53-4636-b754-dd15cc058176",
  "public_token": "public-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d",
  "environment": "sandbox"
}
```

\=\*=\*=\*=

#### 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. This enablement will also cause you to receive the `SESSION_FINISHED` webhook for non-Hosted-Link sessions and to be able to use [/link/token/get](https://plaid.com/docs/api/link/index.html.md#linktokenget) to receive events data for non-Hosted Link sessions.

#### Properties 

string

`LINK`

string

`EVENTS`

\[object\]

The Link events emitted during the Link session

string

Event name

string

Timestamp in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format.

string

UUID that can be used to deduplicate events

object

Metadata about an event that occurred while the user was going through Link

string

The error code that the user encountered. Emitted by `ERROR`, `EXIT`.

string

The error message that the user encountered. Emitted by: `ERROR`, `EXIT`.

string

The error type that the user encountered. Emitted by: `ERROR`, `EXIT`.

string

The status key indicates the point at which the user exited the Link flow. Emitted by: `EXIT`.

string

The ID of the selected institution. Emitted by: all events.

string

The name of the selected institution. Emitted by: all events.

string

The query used to search for institutions. Emitted by: `SEARCH_INSTITUTION`.

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.

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

string

The name of the view that is being transitioned to. Emitted by: `TRANSITION_VIEW`.

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

string

The name of the selected brand.

string

The reason this institution was matched. This will be either `returning_user` or `routing_number` if emitted by `MATCHED_SELECT_INSTITUTION`. Otherwise, this will be `SAVED_INSTITUTION` or `AUTO_SELECT_SAVED_INSTITUTION` if emitted by `SELECT_INSTITUTION`.

string

The routing number submitted by user at the micro-deposits routing number pane. Emitted by `SUBMIT_ROUTING_NUMBER`.

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

string

An identifier for the Link session these events occurred in

string

The Link token used to create the Link session these events are from

API Object

```json
{
  "environment": "sandbox",
  "link_session_id": "1daca4d5-9a0d-4e85-a2e9-1e905ecaa32e",
  "link_token": "link-sandbox-79e723b0-0e04-4248-8a33-15ceb6828a45",
  "webhook_code": "EVENTS",
  "webhook_type": "LINK",
  "events": [
    {
      "event_id": "9469937a-6fac-40be-9322-f86e8c0b94ed",
      "event_metadata": {
        "request_id": "ClqZyuhovgkaQ3j"
      },
      "event_name": "TRANSITION_VIEW",
      "timestamp": "2024-05-21T00:17:54Z"
    },
    {
      "event_id": "4b2390cf-33a2-4078-b933-62468b9e53a5",
      "event_metadata": {
        "error_code": "INVALID_CREDENTIALS",
        "error_message": "the provided credentials were not correct",
        "error_type": "ITEM_ERROR",
        "institution_id": "ins_20",
        "institution_name": "Citizens Bank",
        "request_id": "ttK0NtGKaVAlbCR"
      },
      "event_name": "ERROR",
      "timestamp": "2024-05-21T00:18:09Z"
    },
    {
      "event_id": "45f76afe-f2aa-495c-a326-f37e043a1ccd",
      "event_metadata": {
        "request_id": "WRJqqeh8Hxife05"
      },
      "event_name": "TRANSITION_VIEW",
      "timestamp": "2024-05-21T00:17:56Z"
    },
    {
      "event_id": "978b772c-f2cc-404f-9449-2113e4671c4f",
      "event_metadata": {
        "error_code": "INVALID_CREDENTIALS",
        "error_message": "the provided credentials were not correct",
        "error_type": "ITEM_ERROR",
        "exit_status": "requires_credentials",
        "institution_id": "ins_20",
        "institution_name": "Citizens Bank",
        "request_id": "u1HcAeiCKtz3qmm"
      },
      "event_name": "EXIT",
      "timestamp": "2024-05-21T00:18:13Z"
    },
    {
      "event_id": "a873db76-aa4e-4a00-9d60-7ae08aa8e63f",
      "event_metadata": {
        "institution_id": "ins_20",
        "institution_name": "Citizens Bank",
        "request_id": "ttK0NtGKaVAlbCR"
      },
      "event_name": "TRANSITION_VIEW",
      "timestamp": "2024-05-21T00:18:09Z"
    },
    {
      "event_id": "ca85566d-5f32-4716-909f-82f3a0b6160b",
      "event_metadata": {
        "institution_id": "ins_20",
        "institution_name": "Citizens Bank",
        "request_id": "XRvev3cP9wYUFz5"
      },
      "event_name": "SUBMIT_CREDENTIALS",
      "timestamp": "2024-05-21T00:18:07Z"
    },
    {
      "event_id": "09220752-6b83-407e-baf0-f6228df16ea0",
      "event_metadata": {
        "institution_id": "ins_20",
        "institution_name": "Citizens Bank",
        "request_id": "WRJqqeh8Hxife05"
      },
      "event_name": "SELECT_INSTITUTION",
      "timestamp": "2024-05-21T00:18:01Z"
    },
    {
      "event_id": "1c75d2ee-19c1-4d1b-8600-7d06cecbb270",
      "event_metadata": {
        "institution_id": "ins_20",
        "institution_name": "Citizens Bank",
        "request_id": "5vc1IyBHfLkIVFx"
      },
      "event_name": "TRANSITION_VIEW",
      "timestamp": "2024-05-21T00:18:12Z"
    },
    {
      "event_id": "1c9c9059-c065-4362-836a-d9afb91a6125",
      "event_metadata": {
        "request_id": "MlFW5NSWtCs1KLI"
      },
      "event_name": "TRANSITION_VIEW",
      "timestamp": "2024-05-21T00:17:50Z"
    },
    {
      "event_id": "4f381b3f-172b-4bca-9804-c230f8d36a3b",
      "event_metadata": {
        "institution_id": "ins_20",
        "institution_name": "Citizens Bank",
        "request_id": "XRvev3cP9wYUFz5"
      },
      "event_name": "TRANSITION_VIEW",
      "timestamp": "2024-05-21T00:18:02Z"
    },
    {
      "event_id": "dd9d4747-d4da-4c11-88d6-b5a0e96f1886",
      "event_metadata": {
        "request_id": "ClqZyuhovgkaQ3j"
      },
      "event_name": "SKIP_SUBMIT_PHONE",
      "timestamp": "2024-05-21T00:17:55Z"
    }
  ]
}
```

\=\*=\*=\*=

#### 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), a Multi-Item Link flow, or a Layer flow. If you would like to receive this webhook for other sessions, contact your account manager or support. This enablement will also enable the `EVENTS` webhook for all Link sessions and the ability to use [/link/token/get](https://plaid.com/docs/api/link/index.html.md#linktokenget) to retrieve events for non-Hosted-Link sessions.

#### Properties 

string

`LINK`

string

`SESSION_FINISHED`

string

The final status of the Link session. Will always be "SUCCESS" or "EXITED".

string

The identifier for the Link session.

string

The link token used to create the Link session.

deprecated, string

The public token generated by the Link session. This field has been deprecated; please use `public_tokens` instead.

\[string\]

The public tokens generated by the Link session.

string

The Plaid `user_id` of the User associated with this webhook, warning, or error.

string

The Plaid environment the webhook was sent from

Possible values: `sandbox`, `production`

API Object

```json
{
  "webhook_type": "LINK",
  "webhook_code": "SESSION_FINISHED",
  "status": "SUCCESS",
  "link_session_id": "356dbb28-7f98-44d1-8e6d-0cec580f3171",
  "link_token": "link-sandbox-af1a0311-da53-4636-b754-dd15cc058176",
  "public_tokens": [
    "public-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d"
  ],
  "environment": "sandbox"
}
```