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
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.
template_id
requiredstring
The id of a template defined in Plaid Dashboard
user
object
SessionTokenCreateRequestUser defines per-session user-specific data for /session/token/create
client_user_id
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.
redirect_uri
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. 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.
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
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
link
object
Response data for /session/token/create intended for use with the Link SDK.
link_token
string
A Link token, which can be supplied to Link in order to initialize it and receive a public_token.
expiration
string
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}

/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
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.
public_token
requiredstring
The public token generated by the end user Layer session.
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
nullableobject
The identity data permissioned by the end user during the authorization flow.
name
nullableobject
The user's first name and last name.
address
nullableobject
The user's address.
city
nullablestring
The full city name
region
nullablestring
The region or state. Example: "NC"
street
nullablestring
The full street address Example: "564 Main Street, APT 15"
street2
nullablestring
The second line street address
postal_code
nullablestring
The postal code. In API versions 2018-05-22 and earlier, this field is called zip.
country
nullablestring
The ISO 3166-1 alpha-2 country code
phone_number
string
The user's phone number in E.164 format
email
nullablestring
The user's email address.
Note: email is currently not returned for users, and is an upcoming addition that will be live in early 2025.
date_of_birth
nullablestring
The user's date of birth.
ssn
nullablestring
The user's social security number.
ssn_last_4
nullablestring
The last 4 digits of the user's social security number.
items
[object]
item_id
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.
access_token
string
The access token associated with the Item data is being requested for.
request_id
string
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}

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.

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

Possible values: sandbox, production
link_session_id
string
An identifier for the Link session these events occurred in
link_token
string
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}