Get Link Token

POST /link/token/get

The /link/token/get endpoint gets information about a Link session, including all callbacks fired during the session along with their metadata, including the public token. This endpoint is used with Link flows that don't provide a public token via frontend callbacks, such as the Hosted Link flow and the Multi-Item Link flow. It also can be useful for debugging purposes.

By default, this endpoint will only return complete event data for Hosted Link sessions. To use /link/token/get 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 Body

Required

LinkTokenGetRequest defines the request schema for /link/token/get

Parameters

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
required, string
A link_token from a previous invocation of /link/token/create

Response

LinkTokenGetResponse defines the response schema for /link/token/get

Response Properties

link_token
required, string
A link_token, which can be supplied to Link in order to initialize it and receive a public_token, which can be exchanged for an access_token.
created_at
required, string
The creation timestamp for the link_token, in ISO 8601 format.
expiration
required, string
The expiration timestamp for the link_token, in ISO 8601 format.
link_sessions
array[object]
Information about Link sessions created using this link_token. Session data will be provided for up to six hours after the session has ended.
link_session_id
required, string
The unique ID for the link session.
started_at
string
The timestamp at which the link session was first started, in ISO 8601 format.
finished_at
string
The timestamp at which the link session was finished, if available, in ISO 8601 format.
on_success
object
An object representing an onSuccess callback from Link. This object has been deprecated in favor of the newer results.item_add_result, which can support multiple public tokens in a single Link session.
public_token
required, string
Displayed once a user has successfully linked their Item.
metadata
required, object
Displayed once a user has successfully linked their Item.
institution
object
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
array[object]
A list of accounts attached to the connected Item. If Account Select is enabled via the developer dashboard, accounts will only include selected accounts.
id
string
The Plaid account_id
name
string
The official account name
mask
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.
type
string
The account type. See the Account schema for a full list of possible values
subtype
string
The account subtype. See the Account schema for a full list of possible values
verification_status
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.
class_type
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.
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
string
The status of a transfer. Returned only when Transfer UI is implemented.
  • COMPLETE – The transfer was completed.
  • INCOMPLETE – The transfer could not be completed. For help, see Troubleshooting transfers.
on_exit
object
An object representing an onExit callback from Link. This field has been deprecated in favor of exit, for improved naming consistency.
error
required, 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.
error_type
required, string
A broad categorization of the error. Safe for programmatic use.
error_code
required, string
The particular error code. Safe for programmatic use.
error_code_reason
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.
error_message
required, string
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.
display_message
required, 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.
request_id
string
A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks.
causes
array
In this product, a request can pertain to more than one Item. If an error is returned for such a request, causes will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified. causes will 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.
status
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.
documentation_url
string
The URL of a Plaid documentation page with more information about the error
suggested_action
string
Suggested steps for resolving the error
metadata
required, object
Displayed if a user exits Link without successfully linking an Item.
institution
object
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
object
An object representing an onExit callback from Link.
error
required, 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.
error_type
required, string
A broad categorization of the error. Safe for programmatic use.
error_code
required, string
The particular error code. Safe for programmatic use.
error_code_reason
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.
error_message
required, string
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.
display_message
required, 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.
request_id
string
A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks.
causes
array
In this product, a request can pertain to more than one Item. If an error is returned for such a request, causes will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified. causes will 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.
status
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.
documentation_url
string
The URL of a Plaid documentation page with more information about the error
suggested_action
string
Suggested steps for resolving the error
metadata
required, object
Displayed if a user exits Link without successfully linking an Item.
institution
object
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
array[object]
List of customer-related Link events
event_name
required, string
Event name
timestamp
required, string
Timestamp in ISO 8601 format.
event_id
required, string
UUID that can be used to deduplicate events
event_metadata
required, object
Metadata about an event that occurred while the user was going through Link
error_code
string
The error code that the user encountered. Emitted by ERROR, EXIT.
error_message
string
The error message that the user encountered. Emitted by: ERROR, EXIT.
error_type
string
The error type that the user encountered. Emitted by: ERROR, EXIT.
exit_status
string
The status key indicates the point at which the user exited the Link flow. Emitted by: EXIT.
institution_id
string
The ID of the selected institution. Emitted by: all events.
institution_name
string
The name of the selected institution. Emitted by: all events.
institution_search_query
string
The query used to search for institutions. Emitted by: SEARCH_INSTITUTION.
request_id
string
The request ID for the last request made by Link. This can be shared with Plaid Support to expedite investigation. Emitted by: all events.
mfa_type
string
If set, the user has encountered one of the following MFA types: code, device, questions, selections. Emitted by: SUBMIT_MFA and TRANSITION_VIEW when view_name is MFA.
view_name
string
The name of the view that is being transitioned to. Emitted by: TRANSITION_VIEW.
selection
string
Either the verification method for a matched institution selected by the user or the Auth Type Select flow type selected by the user. If selection is used to describe selected verification method, then possible values are phoneotp or password; if selection is used to describe the selected Auth Type Select flow, then possible values are flow_type_manual or flow_type_instant. Emitted by: MATCHED_SELECT_VERIFY_METHOD and SELECT_AUTH_TYPE.
brand_name
string
The name of the selected brand.
match_reason
string
The reason this institution was matched. 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.
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
object
The set of results for a Link session.
item_add_results
required, array[object]
The set of Item adds for the Link session.
public_token
required, string
Returned once a user has successfully linked their Item.
accounts
required, array[object]
A list of accounts attached to the connected Item. If Account Select is enabled via the developer dashboard, accounts will only include selected accounts.
id
string
The Plaid account_id
name
string
The official account name
mask
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.
type
string
The account type. See the Account schema for a full list of possible values
subtype
string
The account subtype. See the Account schema for a full list of possible values
verification_status
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.
class_type
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.
institution
required, object
An institution object. If the Item was created via Same-Day or Instant micro-deposit verification, will be null.
name
string
The full institution name, such as 'Wells Fargo'
institution_id
string
The Plaid institution identifier
cra_item_add_results
required, array[object]
The set of Plaid Check Item adds for the Link session.
item_id
required, string
The Plaid Check Item ID. The item_id is always unique; linking the same account at the same institution twice will result in two Items with different item_id values. The item_id is case-sensitive.
accounts
required, array[object]
A list of accounts attached to the connected Item. If Account Select is enabled via the developer dashboard, accounts will only include selected accounts.
id
string
The Plaid account_id
name
string
The official account name
mask
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.
type
string
The account type. See the Account schema for a full list of possible values
subtype
string
The account subtype. See the Account schema for a full list of possible values
verification_status
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.
class_type
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.
institution
required, object
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
required, array[object]
The set of bank income verifications for the Link session.
status
required, 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.
item_id
required, string
The Plaid Item ID. The item_id is always unique; linking the same account at the same institution twice will result in two Items with different item_id values. Like all Plaid identifiers, the item_id is case-sensitive.
institution
required, object
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
required, array[object]
The set of payroll income verifications for the Link session.
num_paystubs_retrieved
required, integer
The number of paystubs retrieved from a payroll provider.
num_w2s_retrieved
required, integer
The number of W-2s retrieved from a payroll provider.
institution
required, object
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
required, object
The details of a document income verification in Link
num_paystubs_uploaded
required, integer
The number of paystubs uploaded by the user.
num_w2s_uploaded
required, integer
The number of w2s uploaded by the user.
num_bank_statements_uploaded
required, integer
The number of bank statements uploaded by the user.
num_1099s_uploaded
required, integer
The number of 1099s uploaded by the user
cra_document_upload_results
object
The details of a document upload CRA session in link
num_bank_statements_uploaded
required, integer
The number of bank statements uploaded by the user.
protect_results
object
Plaid Protect details from the Link session
event_id
required, string
The Plaid Protect event ID representing the completion of the link session.
trust_index
object
Represents a calculate Trust Index Score.
score
required, integer
The overall trust index score.
model
required, string
The versioned name of the Trust Index model used for scoring.
subscores
required, object
Contains sub-score metadata.
fraud_attributes
object
Contains attributes used during a trust index calculation.
metadata
required, object
An object specifying the arguments originally provided to the /link/token/create call.
initial_products
required, array[string]
The products specified in the /link/token/create call.
webhook
required, string
The webhook specified in the /link/token/create call.
country_codes
required, array[string]
The country_codes specified in the /link/token/create call.
language
required, string
The language specified in the /link/token/create call.
institution_data
object
A map containing data used to highlight institutions in Link.
routing_number
string
The routing number of the bank to highlight in Link. Note: in rare cases, a single routing number can be associated with multiple institutions, e.g. due to a brokerage using another institution to manage ACH on its sweep accounts. If this happens, the bank will not be highlighted in Link even if the routing number is provided.
account_filters
object
The account_filters specified in the original call to /link/token/create.
depository
object
A filter to apply to depository-type accounts
account_subtypes
required, array[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.
credit
object
A filter to apply to credit-type accounts
account_subtypes
required, array[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.
loan
object
A filter to apply to loan-type accounts
account_subtypes
required, array[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.
investment
object
A filter to apply to investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier).
account_subtypes
required, array[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.
redirect_uri
required, string
The redirect_uri specified in the /link/token/create call.
client_name
required, string
The client_name specified in the /link/token/create call.
request_id
required, string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.