--- title: "Get Link Token" method: POST path: "/link/token/get" tags: ["plaid"] --- # Get Link Token `POST /link/token/get` The `/link/token/get` endpoint gets information about a previously-created `link_token` using the `/link/token/create` endpoint. It can be useful for debugging purposes. ## Request body - LinkTokenGetRequest — LinkTokenGetRequest defines the request schema for `/link/token/get` - `client_id` string — Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. - `secret` string — Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. - `link_token` string, required — A `link_token` from a previous invocation of `/link/token/create` ## Response `200` OK - LinkTokenGetResponse — LinkTokenGetResponse defines the response schema for `/link/token/get` - `link_token` string, required — A `link_token`, which can be supplied to Link in order to initialize it and receive a `public_token`, which can be exchanged for an `access_token`. - `created_at` string, date-time, nullable, required — The creation timestamp for the `link_token`, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format. - `expiration` string, date-time, nullable, required — The expiration timestamp for the `link_token`, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format. - `link_sessions` LinkTokenGetSessionsResponse[] — Information about Link sessions created using this `link_token`. This field will only be present if your client is enabled for Backend Handoff. Session data will be provided for up to six hours after the session has ended. - `link_session_id` string, required — The unique ID for the link session. - `started_at` string, date-time — The timestamp at which the link session was first started, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format. - `finished_at` string, date-time, nullable — The timestamp at which the link session was finished, if available, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format. - `on_success` LinkSessionSuccess, nullable — An object representing an [onSuccess](https://plaid.com/docs/link/web/#onsuccess) callback from Link. - `public_token` string, required — Displayed once a user has successfully linked their Item. - `metadata` LinkSessionSuccessMetadata, nullable, required — Displayed once a user has successfully linked their Item. - `institution` LinkSessionSuccessMetadataInstitution, nullable — An institution object. If the Item was created via Same-Day or Instant micro-deposit verification, will be `null`. - `name` string — The full institution name, such as `'Wells Fargo'` - `institution_id` string — The Plaid institution identifier - `accounts` LinkSessionSuccessMetadataAccount[] — A list of accounts attached to the connected Item. If Account Select is enabled via the developer dashboard, `accounts` will only include selected accounts. - `id` string — The Plaid `account_id` - `name` string — The official account name - `mask` string, nullable — The last 2-4 alphanumeric characters of an account's official account number. Note that the mask may be non-unique between an Item's accounts. It may also not match the mask that the bank displays to the user. - `type` string — The account type. See the [Account schema](/docs/api/accounts#account-type-schema) for a full list of possible values - `subtype` string — The account subtype. See the [Account schema](/docs/api/accounts#account-type-schema) for a full list of possible values - `verification_status` string, nullable — Indicates an Item's micro-deposit-based verification or database verification status. Possible values are: `pending_automatic_verification`: The Item is pending automatic verification `pending_manual_verification`: The Item is pending manual micro-deposit verification. Items remain in this state until the user successfully verifies the code. `automatically_verified`: The Item has successfully been automatically verified `manually_verified`: The Item has successfully been manually verified `verification_expired`: Plaid was unable to automatically verify the deposit within 7 calendar days and will no longer attempt to validate the Item. Users may retry by submitting their information again through Link. `verification_failed`: The Item failed manual micro-deposit verification because the user exhausted all 3 verification attempts. Users may retry by submitting their information again through Link. `database_matched`: The Item has successfully been verified using Plaid's data sources. `database_insights_pending`: The Database Insights result is pending and will be available upon Auth request. Note: Database Insights is currently a beta feature, please contact your account manager for more information. `null`: Neither micro-deposit-based verification nor database verification are being used for the Item. - `class_type` string, nullable — If micro-deposit verification is being used, indicates whether the account being verified is a `business` or `personal` account. - `link_session_id` string — A unique identifier associated with a user's actions and events through the Link flow. Include this identifier when opening a support ticket for faster turnaround. - `transfer_status` 'COMPLETE' | 'INCOMPLETE', nullable — The status of a transfer. Returned only when [Transfer UI](/docs/transfer/using-transfer-ui) is implemented. - `COMPLETE` – The transfer was completed. - `INCOMPLETE` – The transfer could not be completed. For help, see [Troubleshooting transfers](/docs/transfer/using-transfer-ui#troubleshooting-transfers). - `on_exit` LinkSessionExitDeprecated, nullable — An object representing an [onExit](https://plaid.com/docs/link/web/#onexit) callback from Link. - `error` PlaidError, nullable, required — Errors are identified by `error_code` and categorized by `error_type`. Use these in preference to HTTP status codes to identify and handle specific errors. HTTP status codes are set and provide the broadest categorization of errors: 4xx codes are for developer- or user-related errors, and 5xx codes are for Plaid-related errors, and the status will be 2xx in non-error cases. An Item with a non-`null` error object will only be part of an API response when calling `/item/get` to view Item status. Otherwise, error fields will be `null` if no error has occurred; if an error has occurred, an error code will be returned instead. - `error_type` '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', required — A broad categorization of the error. Safe for programmatic use. - `error_code` string, required — The particular error code. Safe for programmatic use. - `error_message` string, required — A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use. - `display_message` string, nullable, required — A user-friendly representation of the error code. `null` if the error is not related to user action. This may change over time and is not safe for programmatic use. - `request_id` string — A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks. - `causes` unknown[] — In the Assets product, a request can pertain to more than one Item. If an error is returned for such a request, `causes` will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified. `causes` will only be provided for the `error_type` `ASSET_REPORT_ERROR`. `causes` will also not be populated inside an error nested within a `warning` object. - unknown - `status` integer, nullable — The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook. - `documentation_url` string — The URL of a Plaid documentation page with more information about the error - `suggested_action` string, nullable — Suggested steps for resolving the error - `metadata` LinkSessionExitMetadata, nullable, required — Displayed if a user exits Link without successfully linking an Item. - `institution` LinkSessionExitMetadataInstitution, nullable — An institution object. If the Item was created via Same-Day or Instant micro-deposit verification, will be `null`. - `name` string — The full institution name, such as `Wells Fargo` - `institution_id` string — The Plaid institution identifier - `status` string — The point at which the user exited the Link flow. One of the following values. - `link_session_id` string — A unique identifier associated with a user's actions and events through the Link flow. Include this identifier when opening a support ticket for faster turnaround. - `request_id` string — The request ID for the last request made by Link. This can be shared with Plaid Support to expedite investigation. - `exit` LinkSessionExit, nullable — An object representing an [onExit](https://plaid.com/docs/link/web/#onexit) callback from Link. - `error` PlaidError, nullable, required — Errors are identified by `error_code` and categorized by `error_type`. Use these in preference to HTTP status codes to identify and handle specific errors. HTTP status codes are set and provide the broadest categorization of errors: 4xx codes are for developer- or user-related errors, and 5xx codes are for Plaid-related errors, and the status will be 2xx in non-error cases. An Item with a non-`null` error object will only be part of an API response when calling `/item/get` to view Item status. Otherwise, error fields will be `null` if no error has occurred; if an error has occurred, an error code will be returned instead. - `error_type` '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', required — A broad categorization of the error. Safe for programmatic use. - `error_code` string, required — The particular error code. Safe for programmatic use. - `error_message` string, required — A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use. - `display_message` string, nullable, required — A user-friendly representation of the error code. `null` if the error is not related to user action. This may change over time and is not safe for programmatic use. - `request_id` string — A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks. - `causes` unknown[] — In the Assets product, a request can pertain to more than one Item. If an error is returned for such a request, `causes` will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified. `causes` will only be provided for the `error_type` `ASSET_REPORT_ERROR`. `causes` will also not be populated inside an error nested within a `warning` object. - unknown - `status` integer, nullable — The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook. - `documentation_url` string — The URL of a Plaid documentation page with more information about the error - `suggested_action` string, nullable — Suggested steps for resolving the error - `metadata` LinkSessionExitMetadata, nullable, required — Displayed if a user exits Link without successfully linking an Item. - `institution` LinkSessionExitMetadataInstitution, nullable — An institution object. If the Item was created via Same-Day or Instant micro-deposit verification, will be `null`. - `name` string — The full institution name, such as `Wells Fargo` - `institution_id` string — The Plaid institution identifier - `status` string — The point at which the user exited the Link flow. One of the following values. - `link_session_id` string — A unique identifier associated with a user's actions and events through the Link flow. Include this identifier when opening a support ticket for faster turnaround. - `request_id` string — The request ID for the last request made by Link. This can be shared with Plaid Support to expedite investigation. - `events` LinkEvent[] — List of customer-related Link events - `event_name` string, required — Event name - `timestamp` string, required — Timestamp in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format. - `event_id` string, required — UUID that can be used to deduplicate events - `event_metadata` LinkEventMetadata, required — Metadata about an event that occured while the user was going through Link - `error_code` string — The error code that the user encountered. Emitted by `ERROR`, `EXIT`. - `error_message` string — The error message that the user encountered. Emitted by: `ERROR`, `EXIT`. - `error_type` string — The error type that the user encountered. Emitted by: `ERROR`, `EXIT`. - `exit_status` string — The status key indicates the point at which the user exited the Link flow. Emitted by: `EXIT`. - `institution_id` string — The ID of the selected institution. Emitted by: all events. - `institution_name` string — The name of the selected institution. Emitted by: all events. - `institution_search_query` string — The query used to search for institutions. Emitted by: `SEARCH_INSTITUTION`. - `request_id` string, required — The request ID for the last request made by Link. This can be shared with Plaid Support to expedite investigation. Emitted by: all events. - `mfa_type` string — If set, the user has encountered one of the following MFA types: code, device, questions, selections. Emitted by: `SUBMIT_MFA` and `TRANSITION_VIEW` when view_name is `MFA`. - `view_name` string — The name of the view that is being transitioned to. Emitted by: `TRANSITION_VIEW`. - `selection` string — Either the verification method for a matched institution selected by the user or the Auth Type Select flow type selected by the user. If selection is used to describe selected verification method, then possible values are `phoneotp` or `password`; if selection is used to describe the selected Auth Type Select flow, then possible values are `flow_type_manual` or `flow_type_instant`. Emitted by: `MATCHED_SELECT_VERIFY_METHOD` and `SELECT_AUTH_TYPE`. - `brand_name` string — The name of the selected brand. - `match_reason` string — The reason this institution was matched, which will be either `returning_user` or `routing_number`. Emitted by: `MATCHED_SELECT_INSTITUTION`. - `routing_number` string — The routing number submitted by user at the micro-deposits routing number pane. Emitted by `SUBMIT_ROUTING_NUMBER`. - `account_number_mask` string — The account number mask extracted from the user-provided account number. If the user-inputted account number is four digits long, `account_number_mask` is empty. Emitted by `SUBMIT_ACCOUNT_NUMBER`. - `results` LinkSessionResults, nullable — The set of results for a Link session. - `item_add_results` LinkSessionItemAddResult[] — The set of Item adds for the Link session. - `public_token` string, required — Returned once a user has successfully linked their Item. - `accounts` LinkSessionSuccessMetadataAccount[], required — A list of accounts attached to the connected Item. If Account Select is enabled via the developer dashboard, `accounts` will only include selected accounts. - `id` string — The Plaid `account_id` - `name` string — The official account name - `mask` string, nullable — The last 2-4 alphanumeric characters of an account's official account number. Note that the mask may be non-unique between an Item's accounts. It may also not match the mask that the bank displays to the user. - `type` string — The account type. See the [Account schema](/docs/api/accounts#account-type-schema) for a full list of possible values - `subtype` string — The account subtype. See the [Account schema](/docs/api/accounts#account-type-schema) for a full list of possible values - `verification_status` string, nullable — Indicates an Item's micro-deposit-based verification or database verification status. Possible values are: `pending_automatic_verification`: The Item is pending automatic verification `pending_manual_verification`: The Item is pending manual micro-deposit verification. Items remain in this state until the user successfully verifies the code. `automatically_verified`: The Item has successfully been automatically verified `manually_verified`: The Item has successfully been manually verified `verification_expired`: Plaid was unable to automatically verify the deposit within 7 calendar days and will no longer attempt to validate the Item. Users may retry by submitting their information again through Link. `verification_failed`: The Item failed manual micro-deposit verification because the user exhausted all 3 verification attempts. Users may retry by submitting their information again through Link. `database_matched`: The Item has successfully been verified using Plaid's data sources. `database_insights_pending`: The Database Insights result is pending and will be available upon Auth request. Note: Database Insights is currently a beta feature, please contact your account manager for more information. `null`: Neither micro-deposit-based verification nor database verification are being used for the Item. - `class_type` string, nullable — If micro-deposit verification is being used, indicates whether the account being verified is a `business` or `personal` account. - `institution` LinkSessionSuccessMetadataInstitution, nullable, required — An institution object. If the Item was created via Same-Day or Instant micro-deposit verification, will be `null`. - `name` string — The full institution name, such as `'Wells Fargo'` - `institution_id` string — The Plaid institution identifier - `bank_income_results` LinkSessionBankIncomeResult[] — The set of bank income verifications for the Link session. - `status` 'APPROVED' | 'NO_DEPOSITS_FOUND' | 'USER_REPORTED_NO_INCOME', required — 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. - `item_id` string, required — The Plaid Item ID. The `item_id` is always unique; linking the same account at the same institution twice will result in two Items with different `item_id` values. Like all Plaid identifiers, the `item_id` is case-sensitive. - `institution` LinkSessionSuccessMetadataInstitution, nullable, required — An institution object. If the Item was created via Same-Day or Instant micro-deposit verification, will be `null`. - `name` string — The full institution name, such as `'Wells Fargo'` - `institution_id` string — The Plaid institution identifier - `payroll_income_results` LinkSessionPayrollIncomeResult[] — The set of payroll income verifications for the Link session. - `num_paystubs_retrieved` integer, required — The number of paystubs retrieved from a payroll provider. - `num_w2s_retrieved` integer, required — The number of W-2s retrieved from a payroll provider. - `institution` LinkSessionSuccessMetadataInstitution, nullable, required — An institution object. If the Item was created via Same-Day or Instant micro-deposit verification, will be `null`. - `name` string — The full institution name, such as `'Wells Fargo'` - `institution_id` string — The Plaid institution identifier - `document_income_results` CreditSessionDocumentIncomeResult, nullable — The details of a document income verification in Link - `num_paystubs_uploaded` integer, required — The number of paystubs uploaded by the user. - `num_w2s_uploaded` integer, required — The number of w2s uploaded by the user. - `num_bank_statements_uploaded` integer, required — The number of bank statements uploaded by the user. - `num_1099s_uploaded` integer, required — The number of 1099s uploaded by the user - `metadata` LinkTokenGetMetadataResponse, required — An object specifying the arguments originally provided to the `/link/token/create` call. - `initial_products` Products[], required — The `products` specified in the `/link/token/create` call. - `webhook` string, nullable, required — The `webhook` specified in the `/link/token/create` call. - `country_codes` CountryCode[], required — The `country_codes` specified in the `/link/token/create` call. - `language` string, nullable, required — The `language` specified in the `/link/token/create` call. - `institution_data` LinkTokenCreateInstitutionData — A map containing data used to highlight institutions in Link. - `routing_number` string — The routing number of the bank to highlight in Link. Note: in rare cases, a single routing number can be associated with multiple institutions, e.g. due to a brokerage using another institution to manage ACH on its sweep accounts. If this happens, the bank will not be highlighted in Link even if the routing number is provided. - `account_filters` AccountFiltersResponse — The `account_filters` specified in the original call to `/link/token/create`. - `depository` DepositoryFilter — A filter to apply to `depository`-type accounts - `account_subtypes` DepositoryAccountSubtype[], required — 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#account-type-schema). - `credit` CreditFilter — A filter to apply to `credit`-type accounts - `account_subtypes` CreditAccountSubtype[], required — 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#account-type-schema). - `loan` LoanFilter — A filter to apply to `loan`-type accounts - `account_subtypes` LoanAccountSubtype[], required — 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#account-type-schema). - `investment` InvestmentFilter — A filter to apply to `investment`-type accounts (or `brokerage`-type accounts for API versions 2018-05-22 and earlier). - `account_subtypes` InvestmentAccountSubtype[], required — 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#account-type-schema). - `redirect_uri` string, nullable, required — The `redirect_uri` specified in the `/link/token/create` call. - `client_name` string, nullable, required — The `client_name` specified in the `/link/token/create` call. - `user_token` string — The user token associated with the User data is being requested for. - `request_id` string, required — A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. ## Changes - **2024-05-10** `a5b45bccb4e8` — 7 breaking, 3 info - the response property `link_sessions/items/results/bank_income_results` became optional for the status `200` - the response property `link_sessions/items/results/document_income_results` became optional for the status `200` - the response property `link_sessions/items/results/item_add_results` became optional for the status `200` - the response property `link_sessions/items/results/payroll_income_results` became optional for the status `200` - …6 more - **2024-05-03** `1550c043ed31` — 3 info - added the optional property `link_sessions/items/exit` to the response with the `200` status - added the optional property `link_sessions/items/results` to the response with the `200` status - added the optional property `metadata/user_token` to the response with the `200` status - **2024-04-17** `943c632a075c` — 1 warning - added the new `profile` enum value to the `metadata/initial_products/items/` response property for the response status `200` - …earlier changes not shown [Full history](https://skmtc.dev/plaid/apis/the-plaid-api/changes/link/token/get/post.md) --- [API](https://skmtc.dev/plaid/apis/the-plaid-api.md) · [All operations](https://skmtc.dev/plaid/apis/the-plaid-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/plaid/the-plaid-api/revisions/a5b45bccb4e8/schema)