Plaid logo
Docs
ALL DOCS

API

  • Overview
  • Libraries
  • API versioning
  • Postman Collection
  • Webhooks
Payments and Funding
  • Auth
  • Balance
  • Identity
  • Signal
  • Transfer
  • Investments Move
  • Payment Initiation
  • Virtual Accounts
Financial Insights
  • Transactions
  • Investments
  • Liabilities
  • Enrich
KYC/AML and anti-fraud
  • Look up Dashboard users
  • Identity Verification
  • Protect
  • Monitor
  • Beacon (beta)
Instant Onboarding
  • Layer
Credit and Underwriting
  • Consumer Report (by Plaid Check)
  • Assets
  • Statements
  • Income
Fundamentals
  • Items
  • Accounts
  • Institutions
  • Sandbox
  • Link
  • Users
  • Consent
  • Network
  • OAuth
Partnerships
  • Processor tokens
  • Processor partners
  • Reseller partners
Plaid logo
Docs
Close search modal
Ask Bill!
Ask Bill!
Hi! I'm Bill! You can ask me all about the Plaid API. Try asking questions like:
    Note: Bill isn't perfect. He's just a robot platypus that reads our docs for fun. You should treat his answers with the same healthy skepticism you might treat any other answer on the internet. This chat may be logged for quality and training purposes. Please don't send Bill any PII -- he's scared of intimacy. All chats with Bill are subject to Plaid's Privacy Policy.
    Plaid.com
    Log in
    Get API Keys
    Open nav

    Layer

    API reference for Layer endpoints

    For how-to guidance, see the Layer documentation.

    Endpoints
    /session/token/createCreates a Link token for a Layer session
    /user_account/session/getReturns user permissioned account data
    Webhooks
    LAYER_AUTHENTICATION_PASSEDA user has been authenticated

    Endpoints

    =*=*=*=

    /session/token/create

    Create a Session Token

    Any Plaid experience a user sees such as connecting a bank account, verifying identity, or sharing a credit report is considered a session. Today, most sessions happen through Link and the token to start these Link session is a link token created and configured via link/token/create. Sessions are a higher level abstraction where configuration primarily happens in Plaid Dashboard. Depending on the template id provided, the session may a Link session, specified by a Link token, or may be another experience in the future. A primary benefit is that configuration changes can be done in Dashboard with no code changes required.
    Currently, this endpoint is only supported for Layer templates and Link but is reserved in the future to initialize other end-user Plaid experiences. The returned Link token is used as an parameter when initializing the Link SDK. For more details, see the Link flow overview.

    session/token/create

    Request fields

    client_id
    stringstring
    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
    stringstring
    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.
    template_id
    requiredstringrequired, string
    The id of a template defined in Plaid Dashboard
    user
    requiredobjectrequired, object
    SessionTokenCreateRequestUser defines per-session user-specific data for /session/token/create
    client_user_id
    requiredstringrequired, 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.
    user_id
    stringstring
    The Plaid user_id of the User associated with this webhook, warning, or error.
    redirect_uri
    stringstring
    A URI indicating the destination where a user should be forwarded after completing the Link flow; used to support OAuth authentication flows when launching Link in the browser or another app. The redirect_uri should not contain any query parameters. When used in Production, must be an https URI. To specify any subdomain, use * as a wildcard character, e.g. https://*.example.com/oauth.html. Note that any redirect URI must also be added to the Allowed redirect URIs list in the developer dashboard. If initializing on Android, android_package_name must be specified instead and redirect_uri should be left blank.
    android_package_name
    stringstring
    The name of your app's Android package. Required if using the session token to initialize Layer 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 session token for initializing Layer on other platforms, android_package_name must be left blank and redirect_uri should be used instead.
    webhook
    stringstring
    The destination URL to which any webhooks should be sent. If you use the same webhook listener for all Sandbox or all Production activity, set this value in the Layer template editor in the Dashboard instead. Only provide a value in this field if you need to use multiple webhook URLs per environment (an uncommon use case). If provided, a value in this field will take priority over webhook values set in the Layer template editor.
    Select Language
    1const request: SessionTokenCreateRequest = {
    2 user: {
    3 client_user_id: 'user-abc'
    4 },
    5 template_id: 'template_4uinBNe4B2x9'
    6};
    7try {
    8 const response = await client.sessionTokenCreate(request);
    9 const linkToken = response.data.link.link_token;
    10} catch (error) {
    11 // handle error
    12}
    session/token/create

    Response fields and example

    request_id
    stringstring
    A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
    link
    objectobject
    Response data for /session/token/create intended for use with the Link SDK.
    link_token
    stringstring
    A Link token, which can be supplied to Link in order to initialize it and receive a public_token.
    expiration
    stringstring
    The expiration date for the link_token, in ISO 8601 format. A link_token created to generate a public_token that will be exchanged for a new access_token expires after 4 hours. 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.

    Format: date-time
    1{
    2 "link": {
    3 "link_token": "link-sandbox-af1a0311-da53-4636-b754-dd15cc058176",
    4 "expiration": "2020-03-27T12:56:34Z"
    5 },
    6 "request_id": "XQVgFigpGHXkb0b"
    7}
    Was this helpful?
    =*=*=*=

    /user_account/session/get

    Retrieve User Account

    Returns user permissioned account data including identity and Item access tokens.

    user_account/session/get

    Request fields

    client_id
    stringstring
    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
    stringstring
    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.
    public_token
    requiredstringrequired, string
    The public token generated by the end user Layer session.
    Select Language
    1const request: UserAccountSessionGetRequest = {
    2 public_token: 'profile-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce992d',
    3};
    4try {
    5 const response = await client.userAccountSessionGet(request);
    6} catch (error) {
    7 // handle error
    8}
    user_account/session/get

    Response fields and example

    identity
    nullableobjectnullable, object
    The identity data permissioned by the end user during the authorization flow.
    name
    nullableobjectnullable, object
    The user's first name and last name.
    first_name
    stringstring
    last_name
    stringstring
    address
    nullableobjectnullable, object
    The user's address.
    city
    nullablestringnullable, string
    The full city name
    region
    nullablestringnullable, string
    The region or state. Example: "NC"
    street
    nullablestringnullable, string
    The full street address Example: "564 Main Street, APT 15"
    street2
    nullablestringnullable, string
    The second line street address
    postal_code
    nullablestringnullable, string
    The postal code. In API versions 2018-05-22 and earlier, this field is called zip.
    country
    nullablestringnullable, string
    The ISO 3166-1 alpha-2 country code
    phone_number
    stringstring
    The user's phone number in E.164 format
    email
    nullablestringnullable, string
    The user's email address.
    Note: email is currently not returned for users, and will be added later in 2025.
    date_of_birth
    nullablestringnullable, string
    The user's date of birth.
    ssn
    nullablestringnullable, string
    The user's social security number.
    ssn_last_4
    nullablestringnullable, string
    The last 4 digits of the user's social security number.
    items
    [object][object]
    item_id
    stringstring
    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.
    access_token
    stringstring
    The access token associated with the Item data is being requested for.
    request_id
    stringstring
    A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
    1{
    2 "identity": {
    3 "name": {
    4 "first_name": "Leslie",
    5 "last_name": "Knope"
    6 },
    7 "address": {
    8 "street": "123 Main St.",
    9 "street2": "",
    10 "city": "Pawnee",
    11 "region": "IN",
    12 "postal_code": "41006",
    13 "country": "US"
    14 },
    15 "email": "leslie@knope.com",
    16 "phone_number": "+14157452130",
    17 "date_of_birth": "1975-01-18",
    18 "ssn": "987654321",
    19 "ssn_last_4": "4321"
    20 },
    21 "items": [
    22 {
    23 "item_id": "Ed6bjNrDLJfGvZWwnkQlfxwoNz54B5C97ejBr",
    24 "access_token": "access-sandbox-435beced-94e8-4df3-a181-1dde1cfa19f0"
    25 }
    26 ],
    27 "request_id": "m8MDnv9okwxFNBV"
    28}
    Was this helpful?

    Webhooks

    =*=*=*=

    LAYER_AUTHENTICATION_PASSED

    Fired when user authentication event occurs within Layer. Receiving this webhook indicates that Plaid's authentication process has completed for a user.

    Properties

    webhook_type
    stringstring
    LAYER
    webhook_code
    stringstring
    LAYER_AUTHENTICATION_PASSED
    environment
    stringstring
    The Plaid environment the webhook was sent from

    Possible values: sandbox, production
    link_session_id
    stringstring
    An identifier for the Link session these events occurred in
    link_token
    stringstring
    The Link token used to create the Link session these events are from
    1{
    2 "webhook_type": "LAYER",
    3 "webhook_code": "LAYER_AUTHENTICATION_PASSED",
    4 "environment": "production",
    5 "link_session_id": "1daca4d5-9a0d-4e85-a2e9-1e905ecaa32e",
    6 "link_token": "link-sandbox-79e723b0-0e04-4248-8a33-15ceb6828a45"
    7}
    Was this helpful?
    Developer community
    GitHub
    GitHub
    Stack Overflow
    Stack Overflow
    YouTube
    YouTube
    Discord
    Discord