Layer 
======

#### API reference for Layer endpoints 

For how-to guidance, see the [Layer documentation](https://plaid.com/docs/layer/index.html.md) .

| Endpoints |  |
| --- | --- |
| [/session/token/create](https://plaid.com/docs/api/products/layer/index.html.md#sessiontokencreate) | Creates a Link token for a Layer session |
| [/user\_account/session/get](https://plaid.com/docs/api/products/layer/index.html.md#user_accountsessionget) | Returns user permissioned account data |

| Webhooks |  |
| --- | --- |
| [LAYER\_AUTHENTICATION\_PASSED](https://plaid.com/docs/api/products/layer/index.html.md#layer_authentication_passed) | A user has been authenticated |
| [SESSION\_FINISHED](https://plaid.com/docs/api/products/layer/index.html.md#session_finished) | A Layer session has finished |

### Endpoints 

\=\*=\*=\*=

#### /session/token/create 

#### Create a Link token for Layer 

[/session/token/create](https://plaid.com/docs/api/products/layer/index.html.md#sessiontokencreate) is used to create a Link token for Layer. The returned Link token is used as a parameter when initializing the Link SDK. For more details, see the [Link flow overview](https://plaid.com/docs/link/index.html.md#link-flow-overview) .

#### Request fields 

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.

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.

required, string

The id of a template defined in Plaid Dashboard

object

Details about the end user. Required if a root-level `user_id` is not provided.

required, 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.

string

The `user_id` created by calling `/user/create`. Provide this field only if you are using Plaid Check Report with Layer and have a `user_token`.

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. Note that any redirect URI must also be added to the Allowed redirect URIs list in the [developer dashboard](https://dashboard.plaid.com/team/api) . If initializing on Android, `android_package_name` must be specified instead and `redirect_uri` should be left blank.

string

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](https://dashboard.plaid.com/team/api) . 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.

string

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.

Format: `url`

string

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](https://plaid.com/docs/api/users/user-apis/index.html.md) .

```node
const request: SessionTokenCreateRequest = {
  user: {
    client_user_id: 'user-abc'
  },
  template_id: 'template_4uinBNe4B2x9'
};
try {
  const response = await client.sessionTokenCreate(request);
  const linkToken = response.data.link.link_token;
} catch (error) {
  // handle error
}

```

```bash
curl -X POST https://sandbox.plaid.com/session/token/create \
-H 'Content-Type: application/json' \
-d '{
  "client_id": "${PLAID_CLIENT_ID}",
  "secret": "${PLAID_SECRET}",
  "user": {
    "client_user_id": "user-abc"
  },
  "template_id": "template_4uinBNe4B2x9"
}'

```

```ruby
request = Plaid::SessionTokenCreateRequest.new(
  {
    user: {
      client_user_id: 'user-abc'
    },
    template_id: 'template_4uinBNe4B2x9'
  }
)
response = client.session_token_create(request)
link_token = response.link.link_token

```

```java
SessionTokenCreateRequestUser user = new SessionTokenCreateRequestUser()
  .clientUserId("user-abc");

SessionTokenCreateRequest request = new SessionTokenCreateRequest()
  .user(user)
  .templateId("template_4uinBNe4B2x9");

Response response = client()
  .sessionTokenCreate(request)
  .execute();

String linkToken = response.body().getLink().getLinkToken();

```

```python
request = SessionTokenCreateRequest(
  user=SessionTokenCreateRequestUser(
    client_user_id='user-abc'
  ),
  template_id='template_4uinBNe4B2x9'
)
response = client.session_token_create(request)
link_token = response['link']['link_token']

```

```go
user := plaid.SessionTokenCreateRequestUser{
  ClientUserId: "user-abc",
}

request := plaid.NewSessionTokenCreateRequest("template_4uinBNe4B2x9")
request.SetUser(user)

response, _, err := client.PlaidApi.
  SessionTokenCreate(ctx).
  SessionTokenCreateRequest(*request).
  Execute()
if err != nil {
  panic(err)
}
linkToken := response.GetLink().GetLinkToken();

```

#### Response fields 

string

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

object

Response data for `/session/token/create` intended for use with the Link SDK.

string

A Link token, which can be supplied to Link in order to initialize it and receive a `public_token`.

string

The expiration date for the `link_token`, in [ISO 8601](https://wikipedia.org/wiki/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`

string

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](https://plaid.com/docs/api/users/user-apis/index.html.md) .

Response Object

```json
{
  "link": {
    "link_token": "link-sandbox-af1a0311-da53-4636-b754-dd15cc058176",
    "expiration": "2020-03-27T12:56:34Z"
  },
  "request_id": "XQVgFigpGHXkb0b"
}
```

\=\*=\*=\*=

#### /user\_account/session/get 

#### Retrieve User Account 

This endpoint returns user permissioned account data, including identity and Item access tokens, for use with [Plaid Layer](https://plaid.com/docs/layer/index.html.md) . Note that end users are permitted to edit the prefilled identity data in the Link flow before sharing it with you; you should treat any identity data returned by this endpoint as user-submitted, unverified data. For a verification layer, you can add [Identity Verification](https://plaid.com/docs/identity-verification/index.html.md) to your flow, or check the submitted identity data against bank account data from linked accounts using [Identity Match](https://plaid.com/docs/identity/index.html.md#identity-match) .

#### Request fields 

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.

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.

required, string

The public token generated by the end user Layer session.

```node
const request: UserAccountSessionGetRequest = {
  public_token: 'profile-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce992d',
};
try {
  const response = await client.userAccountSessionGet(request);
} catch (error) {
  // handle error
}

```

```bash
curl -X POST https://sandbox.plaid.com/user_account/session/get \
-H 'Content-Type: application/json' \
-d '{
  "public_token": "profile-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce992d",
  "client_id": "${PLAID_CLIENT_ID}",
  "secret": "${PLAID_SECRET}"
}'

```

```ruby
request = Plaid::UserAccountSessionGetRequest.new(
  {
    public_token: 'profile-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce992d'
  }
)
response = client.user_account_session_get(request)

```

```java

UserAccountSessionGetRequest request = new UserAccountSessionGetRequest()
  .publicToken("profile-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce992d");

Response response = client()
  .userAccountSessionGet(request)
  .execute();

```

```python
request = UserAccountSessionGetRequest(
    public_token='profile-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce992d'
)
response = client.user_account_session_get(request)

```

```go
request := plaid.NewUserAccountSessionGetRequest(
  "profile-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce992d",
)

response, _, err := client.PlaidApi.
  UserAccountSessionGet(ctx).
  UserAccountSessionGetRequest(*request).
  Execute()

```

#### Response fields 

nullable, object

The identity data permissioned by the end user during the authorization flow.

nullable, object

The user's first name and last name.

string

string

nullable, object

The user's address.

nullable, string

The full city name

nullable, string

The region or state. Example: `"NC"`

nullable, string

The full street address Example: `"564 Main Street, APT 15"`

nullable, string

The second line street address

nullable, string

The postal code. In API versions 2018-05-22 and earlier, this field is called `zip`.

nullable, string

The ISO 3166-1 alpha-2 country code

string

The user's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format

nullable, string

The user's email address.

Note: email is currently not returned.

nullable, string

The user's date of birth.

nullable, string

The user's social security number.

nullable, string

The last 4 digits of the user's social security number.

\[object\]

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.

string

The access token associated with the Item for which data is being requested.

nullable, object

Statistics tracking the number of edits made to identity fields over various time periods.

object

Edit counts over various time periods.

integer

Number of edits in the current session

integer

Number of edits in the last 1 day

integer

Number of edits in the last 30 days

integer

Number of edits in the last 365 days

integer

Total number of edits

object

Edit counts over various time periods.

integer

Number of edits in the current session

integer

Number of edits in the last 1 day

integer

Number of edits in the last 30 days

integer

Number of edits in the last 365 days

integer

Total number of edits

object

Edit counts over various time periods.

integer

Number of edits in the current session

integer

Number of edits in the last 1 day

integer

Number of edits in the last 30 days

integer

Number of edits in the last 365 days

integer

Total number of edits

object

Edit counts over various time periods.

integer

Number of edits in the current session

integer

Number of edits in the last 1 day

integer

Number of edits in the last 30 days

integer

Number of edits in the last 365 days

integer

Total number of edits

nullable, object

Official identity document edit statistics.

object

Edit counts over various time periods.

integer

Number of edits in the current session

integer

Number of edits in the last 1 day

integer

Number of edits in the last 30 days

integer

Number of edits in the last 365 days

integer

Total number of edits

string

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

Response Object

```json
{
  "identity": {
    "name": {
      "first_name": "Leslie",
      "last_name": "Knope"
    },
    "address": {
      "street": "123 Main St.",
      "street2": "",
      "city": "Pawnee",
      "region": "IN",
      "postal_code": "41006",
      "country": "US"
    },
    "email": "leslie@knope.com",
    "phone_number": "+14157452130",
    "date_of_birth": "1975-01-18",
    "ssn": "987654321",
    "ssn_last_4": "4321"
  },
  "identity_edit_history": {
    "name": {
      "edits_current": 0,
      "edits_1d": 0,
      "edits_30d": 1,
      "edits_365d": 1,
      "edits_all_time": 1
    },
    "address": {
      "edits_current": 1,
      "edits_1d": 1,
      "edits_30d": 2,
      "edits_365d": 2,
      "edits_all_time": 2
    },
    "email": {
      "edits_current": 0,
      "edits_1d": 0,
      "edits_30d": 0,
      "edits_365d": 0,
      "edits_all_time": 0
    },
    "date_of_birth": {
      "edits_current": 0,
      "edits_1d": 0,
      "edits_30d": 0,
      "edits_365d": 0,
      "edits_all_time": 0
    },
    "official_document": {
      "ssn": {
        "edits_current": 0,
        "edits_1d": 0,
        "edits_30d": 0,
        "edits_365d": 0,
        "edits_all_time": 0
      }
    }
  },
  "items": [
    {
      "item_id": "Ed6bjNrDLJfGvZWwnkQlfxwoNz54B5C97ejBr",
      "access_token": "access-sandbox-435beced-94e8-4df3-a181-1dde1cfa19f0"
    }
  ],
  "request_id": "m8MDnv9okwxFNBV"
}
```

### Webhooks 

\=\*=\*=\*=

#### LAYER\_AUTHENTICATION\_PASSED 

Indicates that Plaid's authentication process has completed for a user and that Plaid has verified that the user owns their phone number. If you receive this webhook, you should skip your own OTP phone number verification flow for the user, even if the user does not complete the entire Link flow. If the user doesn't complete the full Link flow (as verified by your being able to successfully call [/user\_account/session/get](https://plaid.com/docs/api/products/layer/index.html.md#user_accountsessionget) using the `public_token` from the `onSuccess` callback) it is recommended that you implement [webhook verification](https://plaid.com/docs/api/webhooks/webhook-verification/index.html.md) or another technique to avoid webhook spoofing attacks.

#### Properties 

string

`LAYER`

string

`LAYER_AUTHENTICATION_PASSED`

string

The Plaid environment the webhook was sent from

Possible values: `sandbox`, `production`

string

An identifier for the Link session these events occurred in

string

The Link token used to create the Link session these events are from

API Object

```json
{
  "webhook_type": "LAYER",
  "webhook_code": "LAYER_AUTHENTICATION_PASSED",
  "environment": "production",
  "link_session_id": "1daca4d5-9a0d-4e85-a2e9-1e905ecaa32e",
  "link_token": "link-sandbox-79e723b0-0e04-4248-8a33-15ceb6828a45"
}
```

\=\*=\*=\*=

#### SESSION\_FINISHED 

Contains the state of a completed Link session, along with the public token(s) if available.

By default, this webhook is sent only for sessions enabled for the Hosted Link flow (including Link Recovery flows), a Multi-Item Link flow, or a Layer flow. If you would like to receive this webhook for other sessions, contact your account manager or support. This enablement will also enable the `EVENTS` webhook for all Link sessions and the ability to use [/link/token/get](https://plaid.com/docs/api/link/index.html.md#linktokenget) to retrieve events for non-Hosted-Link sessions.

#### Properties 

string

`LINK`

string

`SESSION_FINISHED`

string

The final status of the Link session. Will always be "SUCCESS" or "EXITED".

string

The identifier for the Link session.

string

The `link_token` used to create the Link session.

deprecated, string

The public token generated by the Link session. This field has been deprecated; please use `public_tokens` instead.

\[string\]

The public tokens generated by the Link session.

string

The Plaid `user_id` of the User associated with this webhook, warning, or error.

string

The Plaid environment the webhook was sent from

Possible values: `sandbox`, `production`

API Object

```json
{
  "webhook_type": "LINK",
  "webhook_code": "SESSION_FINISHED",
  "status": "SUCCESS",
  "link_session_id": "356dbb28-7f98-44d1-8e6d-0cec580f3171",
  "link_token": "link-sandbox-af1a0311-da53-4636-b754-dd15cc058176",
  "public_tokens": [
    "public-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d"
  ],
  "environment": "sandbox"
}
```