plaid

Create Link Token

Changed on

The /link/token/create endpoint creates a link_token, which is required as a parameter when initializing Link. Once Link has been initialized, it returns a public_token. For most Plaid products, the public_token is saved and exchanged for an access_token via /item/public_token/exchange as part of the main Link flow. For more details, see the Link flow overview.

A link_token generated by /link/token/create is also used to initialize other Link flows, such as the update mode flow for tokens with expired credentials, or the Identity Verification flow.

post/link/token/create

Request

  • Base URL
    https://production.plaid.com
  • URL
    https://production.plaid.com/link/token/create
  • Auth
    • API key in header PLAID-CLIENT-ID and API key in header PLAID-SECRET and API key in header Plaid-Version
    • or OAuth 2
      Client credentials
      Token URL: https://api.plaid.com/oauth2/apiv2/token scopes: link:write

Request body

client_idstring

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.

secretstring

Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.

client_namestring required

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.

languagestring required

The language that Link should be displayed in. When initializing with Identity Verification, this field is not used; for more details, see Identity Verification supported languages.

Supported languages are:

  • Danish ('da')
  • Dutch ('nl')
  • English ('en')
  • Estonian ('et')
  • French ('fr')
  • German ('de')
  • Haitian Creole ('ht')
  • Hindi ('hi')
  • Italian ('it')
  • Latvian ('lv')
  • Lithuanian ('lt')
  • Norwegian Bokmål ('nb')
  • 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.

country_codesCountryCode[] required

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 What Plaid products are supported in each country and region?. For access to additional countries beyond what you have been approved for, contact sales, 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 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, or Automated Micro-deposits, country_codes must be set to ['US']. If using Database Auth, country_codes must be set to ['US'] or ['CA'].

user_idstring

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. Required for new integrations that use Payment Initiation, Variable Recurring Payments, or Virtual Accounts. For more details, see New User APIs. One of either the user_id or the user field is required.

productsProducts[] nullable

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.

To add products without limiting the institution list or account types, use the optional_products or 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 array. For details, see Choosing when to initialize products.

balance is not a valid value, the Balance product does not require explicit initialization and will automatically be initialized when any other product is initialized.

If launching Link with CRA products, cra_base_report 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.

required_if_supported_productsProducts[] nullable

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.

optional_productsProducts[] nullable

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.

additional_consented_productsProducts[] nullable

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, required_if_supported_products, or optional_products arrays.

If you include signal in additional_consented_products, you will need to call /signal/prepare before calling /signal/evaluate for the first time on an Item in order to get the most accurate results. For more details, see /signal/prepare.

webhookstring url

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.

access_tokenstring nullable

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 Micro-deposit (manual) flow, or (optionally) when initializing Link for a returning user as part of the Transfer UI flow.

access_tokensstring[]

A list of access tokens associated with the items to update in Link update mode for the Assets product. Using this instead of the access_token field allows the updating of multiple items at once. This feature is in closed beta, please contact your account manager for more info.

link_customization_namestring

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.

appearance_mode'LIGHT' | 'DARK' | 'SYSTEM' | 'null' nullable

Enum representing the desired appearance mode for Link, used to force light or dark modes or set Link to change depending on user system settings. Currently in closed beta.

redirect_uristring

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. If initializing on Android, android_package_name must be specified instead and redirect_uri should be left blank.

android_package_namestring

The name of your app's Android package. Required if using the link_token to initialize Link on Android. Any package name specified here must also be added to the Allowed Android package names setting on the developer dashboard. When creating a link_token for initializing Link on other platforms, android_package_name must be left blank and redirect_uri should be used instead.

institution_idstring

Used for certain legacy use cases

consumer_report_permissible_purpose'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'

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

third_party_user_tokenstring

A third party user token associated with the current user.

cra_enabledboolean

If true, request a CRA connection. Defaults to false.

financekit_supportedboolean

If true, indicates that client supports linking FinanceKit / AppleCard items. Defaults to false.

enable_multi_item_linkboolean

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

user_tokenstring

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.

Example request

{
  "user": {
    "name": {
      "given_name": "Leslie",
      "family_name": "Knope"
    },
    "address": {
      "street": "123 Main St.",
      "street2": "Unit 42",
      "city": "Pawnee",
      "region": "IN",
      "postal_code": "46001",
      "country": "US"
    },
    "id_number": {
      "value": "123456789",
      "type": "us_ssn"
    }
  },
  "identity_verification": {
    "template_id": "idvtmp_4FrXJvfQU3zGUR",
    "consent": true,
    "gave_consent": true
  }
}

Response

OK

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

expirationstring date-time required

The expiration date and time for the link_token, in ISO 8601 format. By default, a link_token created to generate a public_token that will be exchanged for a new access_token expires after 4 hours, and a link_token created for an existing Item (such as when updating an existing access_token by launching Link in update mode) expires after 30 minutes. If using Hosted Link, the link_token will expire at the same time as the Hosted Link URL, and you can customize the duration using the hosted_link.url_lifetime_seconds option in the request. If using Link Delivery (beta), the link_token will expire by default after 24 hours if sent via SMS and after 7 days if sent via email. If using Identity Verification, Link token expiration will not be enforced; an Identity Verification Link session can be created with an expired Link token.

request_idstring required

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

hosted_link_urlstring

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.

user_idstring

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.

Changes

  • ea443cd78f6fRevision changes
    • breaking

      added subschema #2 to the / request property allOf list

    • breaking

      the request property / became required

    • breaking

      the request property / became required

    • breaking

      removed the enum value CLIENT_USER of the request property /

    • breaking

      removed the enum value PLAID_NETWORK of the request property /

    • breaking

      the / request property type changed from string to no type

    • warning

      removed the request property ////

    • warning

      added the new CRA_PARTNER_INSIGHTS_ERROR enum value to the response property for the response status

    • warning

      added the new CRA_REPORT_ERROR enum value to the response property for the response status

    • info

      added the new optional request property /

    • info

      added the new optional request property ////

    • info

      added the new optional request property /

    • info

      added cra_lend_score_complete cra_income_complete discriminator mapping keys to the // request property

    • info

      added to the // request property oneOf list

  • e07a869352e8Revision changes
    • breaking

      removed the enum value charge card of the request property ///

    • breaking

      removed the enum value installment of the request property ///

    • info

      the endpoint scheme security clientId AND secret AND plaidVersion was added to the API

    • info

      the endpoint scheme security oauth2 was added to the API

    • info

      added the new optional request property